Popover

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 and shift middlewares. You might also find the offset middleware useful for adding a gap between the trigger and the popover.

Portals

It is important to know that before calculating the position, the popover gets portaled into the nearest ThemeProvider 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