Popover | iTwinUI

Popover is a utility component for displaying overlay content in a dialog that is placed relative to a trigger element.

import * as React from 'react';
import { Button, Popover } from '@itwin/itwinui-react';

export default () => {
  return (
    <Popover
      content='This is a popover!'
      applyBackground
      style={{ padding: 'var(--iui-size-xs)' }}
    >
      <Button>Toggle</Button>
    </Popover>
  );
};

By default, Popover does not add any styling. The applyBackground prop can be used to add the recommended background, box-shadow, border, etc.

Usage

The content shown inside the Popover is passed using the content prop. The trigger element is specified by the child element that Popover wraps around.

For everything to work correctly, the trigger element must:

be a button
forward its ref
delegate (spread) any arbitrary props

If you use a native <button> or iTwinUI’s <Button> as the trigger, then all of this should be handled for you. Passing a non-interactive element (like <div>) is not advised, as it will break some accessibility expectations.

Positioning

Popover handles positioning using an external library called Floating UI. To control which side the popover should be placed relative to its trigger, use the placement prop. If not enough space is available, then it will flip to the opposite side.

import * as React from 'react';
import { Button, LabeledSelect, Popover } from '@itwin/itwinui-react';

export default () => {
  const [placement, setPlacement] = React.useState('bottom-start');

  return (
    <Popover
      content={
        <div style={{ padding: 'var(--iui-size-xs)' }}>
          <LabeledSelect
            label='Placement'
            options={placements.map((p) => ({ value: p, label: p }))}
            value={placement}
            onChange={setPlacement}
            style={{ minWidth: '20ch' }}
          />
        </div>
      }
      applyBackground
      placement={placement}
    >
      <Button>Adjust placement</Button>
    </Popover>
  );
};

const placements = [
  'bottom',
  'bottom-start',
  'bottom-end',
  'top',
  'top-start',
  'top-end',
  'left',
  'left-start',
  'left-end',
  'right',
  'right-start',
  'right-end',
];

There are some advanced positioning options available.

The positionReference prop can be used to position the popover relative to a different element than the trigger. This can be useful, for example, when the trigger is part of a larger group of elements that should all be considered together.
The middleware prop exposes more granular control over the positioning logic. By default, Popover enables the flip, shift, size, and hide middlewares. You might also find the offset middleware useful for adding a gap between the trigger and the popover.
If the floating content gets hidden even when it shouldn’t (e.g. due to some custom styles interfering with the trigger’s hide detection), consider disabling the hide middleware.

Portals

It is important to know that before calculating the position, the popover gets portaled to the end of <body> to avoid stacking context issues. This behavior can be controlled using the Popover’s portal prop or the ThemeProvider’s portalContainer prop. Using portals can often lead to issues with keyboard accessibility, so Popover adds some additional logic (described below).

Accessibility

Semantically speaking, popovers are dialogs that follow the disclosure pattern. The popover is opened by clicking on the trigger element or by pressing Enter or Space when the trigger has focus. The trigger element should almost always be a <button> underneath (rather than a non-interactive element such as <div>).

The popover should generally be labeled using aria-labelledby. This label can be located inside the popover as a visible heading or hidden text. If aria-labelledby or aria-label is not passed to the Popover, then the trigger element will be used as the label by default. Additionally, an optional aria-describedby can be used for any supplementary text.

When the popover opens, keyboard focus will be moved to the popover. When it closes, keyboard focus will move back to the trigger element. Additionally, keyboard focus will move back to the trigger when tabbing out of it.

If you have a good candidate for receiving focus, then you can manually focus() it using a ref or use autoFocus where possible. This should be done thoughtfully, and the element receiving focus should usually be located near the beginning of the popover, with not too much content preceding it.

The following example shows how you can focus an input when the popover opens. This input is preceded by a heading associated with the popover using aria-labelledby. As a result, when the popover opens, the heading is automatically announced to a screen reader user, ensuring they didn’t miss any content located before the input.

import * as React from 'react';
import {
  Button,
  Flex,
  IconButton,
  LabeledInput,
  Popover,
  Surface,
  Text,
} from '@itwin/itwinui-react';
import { SvgSettings } from '@itwin/itwinui-icons-react';

export default () => {
  const headingId = `${React.useId()}-label`;

  const [isOpen, setIsOpen] = React.useState(false);

  return (
    <Popover
      applyBackground
      aria-labelledby={headingId}
      visible={isOpen}
      onVisibleChange={setIsOpen}
      style={{ maxWidth: '45ch' }}
      content={
        <Surface elevation={0} border={false}>
          <Surface.Header>
            <Text as='h3' id={headingId} variant='leading'>
              Settings
            </Text>
          </Surface.Header>
          <Surface.Body isPadded>
            <Flex flexDirection='column' alignItems='flex-end'>
              {/* this will be focused when popover opens */}
              <LabeledInput label='Quality' autoFocus />

              <LabeledInput label='Grain' />
              <LabeledInput label='Saturation' />

              <Button
                styleType='high-visibility'
                onClick={() => setIsOpen(false)}
              >
                Apply
              </Button>
            </Flex>
          </Surface.Body>
        </Surface>
      }
    >
      <IconButton label='Adjust settings'>
        <SvgSettings />
      </IconButton>
    </Popover>
  );
};

Props

Prop	Description	Default
content	Content displayed inside the popover. ReactNode
children	Element that triggers the popover. Should usually be a button. ReactNode
applyBackground	Whether the popover adds recommended CSS (background-color, box-shadow, etc.) to itself. boolean	false
positionReference	This is used to position the popover relative to a different element than the trigger. Recommended to use state to store this element, rather than a ref. HTMLElement
portal	Where should the element be portaled to? If true, it will portal into nearest ThemeProvider's portalContainer. If false, it will not be portaled. Otherwise, it will portal to the element passed to `to`. If `to`/`to()` === `null`/`undefined`, the default behavior will be used (i.e. as if `portal` is not passed). boolean \| { to: HTMLElement \| (() => HTMLElement); }	true
placement	Placement of the popover content. Placement	'bottom-start'
visible	Controlled flag for whether the popover is visible. boolean
onVisibleChange	Callback invoked every time the popover visibility changes as a result of internal logic. Should be used alongside `visible` prop. (visible: boolean) => void
closeOnOutsideClick	If true, the popover will close when clicking outside it. boolean	true
middleware	Middleware options. By default, `flip`, `shift`, `size`, and `hide` are enabled. If the floating content gets hidden even when it shouldn't (e.g. some custom styles interfering with the trigger's hide detection) consider disabling the `hide` middleware. @see https://floating-ui.com/docs/middleware { offset?: number; flip?: boolean; shift?: boolean; size?: boolean \| { maxHeight?: string; }; autoPlacement?: boolean; hide?: boolean; inline?: boolean; }
as	"symbol" \| "object" \| "dialog" \| "menu" \| "div" \| "a" \| "abbr" \| "address" \| "area" \| "article" \| "aside" \| "audio" \| "b" \| "base" \| "bdi" \| "bdo" \| "big" \| "blockquote" \| "body" \| ... 159 more ... \| FunctionComponent<...>