Forma 36 - Popover

Only if Menu, Autocomplete and Multiselect components are not covering your use cases, you should use Popover.
Before using this component, double-check your design requirements. We are providing Menu, Autocomplete, and Multiselect for more specific use-cases and they can address your needs.
Keep in mind that you will have to implement everything related to accessibility for the popover content.
Component is controllable, so don't forget to pass onClose callback prop. Otherwise closeOnEsc and closeOnBlur will not work properly.

Import

import { Popover } from '@contentful/f36-components';
// or
import { Popover } from '@contentful/f36-popover';

Examples

Basic

Pass trigger component as a child for Popover.Trigger. NOTE: 🚨 Ensure that the component that you pass accepts ref. Consider using forwardRef for functional components.
Pass popover content as a child for Popover.Content


function PopoverBasicExample() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <Popover isOpen={isOpen} onClose={() => setIsOpen(false)}>
      <Popover.Trigger>
        <Button onClick={() => setIsOpen(!isOpen)}>Toggle</Button>
      </Popover.Trigger>
      <Popover.Content>
        <Box padding="spacingM">
          <Paragraph>This is the content.</Paragraph>
          <Button>Some action</Button>
        </Box>
      </Popover.Content>
    </Popover>
  );
}function PopoverBasicExample() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <Popover isOpen={isOpen} onClose={() => setIsOpen(false)}>
      <Popover.Trigger>
        <Button onClick={() => setIsOpen(!isOpen)}>Toggle</Button>
      </Popover.Trigger>
      <Popover.Content>
        <Box padding="spacingM">
          <Paragraph>This is the content.</Paragraph>
          <Button>Some action</Button>
        </Box>
      </Popover.Content>
    </Popover>
  );
}
Open in Playground

If the popover contains interactive elements that user can navigate through with Tab, consider using react-focus-lock to trap the focus within Popover


function PopoverFocusLockExample() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <Popover isOpen={isOpen} onClose={() => setIsOpen(false)}>
      <Popover.Trigger>
        <Button onClick={() => setIsOpen(!isOpen)}>Toggle</Button>
      </Popover.Trigger>
      <Popover.Content>
        {/* Just wrap your content with FocusLock component */}
        <FocusLock>
          <Stack
            padding="spacingM"
            margin="none"
            spacing="spacingS"
            flexDirection="column"
          >
            <Switch>Option 1</Switch>
            <Switch>Option 2</Switch>
            <Switch>Option 3</Switch>
          </Stack>
        </FocusLock>
      </Popover.Content>
    </Popover>
  );
}function PopoverFocusLockExample() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <Popover isOpen={isOpen} onClose={() => setIsOpen(false)}>
      <Popover.Trigger>
        <Button onClick={() => setIsOpen(!isOpen)}>Toggle</Button>
      </Popover.Trigger>
      <Popover.Content>
        {/* Just wrap your content with FocusLock component */}
        <FocusLock>
          <Stack
            padding="spacingM"
            margin="none"
            spacing="spacingS"
            flexDirection="column"
          >
            <Switch>Option 1</Switch>
            <Switch>Option 2</Switch>
            <Switch>Option 3</Switch>
          </Stack>
        </FocusLock>
      </Popover.Content>
    </Popover>
  );
}
Open in Playground

Props (API reference)

Open in Storybook

Name	Type	Default
children required	ReactNode
autoFocus	false true If true, the popover will be focused after opening	true
closeOnBlur	false true If true, the popover will close when you blur out it by clicking outside or tabbing out	true
closeOnEsc	false true If true, the popover will close when you hit the Esc key	true
id	string Popover id. Will be used as an `id` attribute on popover and as `aria-controls` attribute on trigger	true
isAutoalignmentEnabled	false true Boolean to control if popover is allowed to change its placement automatically based on available space in the viewport. For example: If you set placement prop to bottom, but there isn't enough space to position the popover in that direction, it will change the popper placement to top. As soon as enough space is detected, the placement will be reverted to the defined one. If you want the popover to strictly follow the placement prop you should set this prop to false.	true
isFullWidth	false true Boolean to determine if the Popover should be the same width as the trigger element	false
isOpen	false true Boolean to control whether or not the Popover is open	false
offset	[number, number] The `X-axis` and `Y-axis` offset to position popper element from its trigger element. `[X, Y]`	[1, 4]
onClose	() => void Callback fired when the popover closes
placement	"auto" "auto-start" "auto-end" "top" "bottom" "right" "left" "top-start" "top-end" "bottom-start" "bottom-end" "right-start" "right-end" "left-start" "left-end" Determines the preferred position of the Popover. This position is not guaranteed, as the Popover might be moved to fit the viewport	bottom-start
renderOnlyWhenOpen	false true Defines if popover should be rendered in the DOM only when it's open or all the time (after the component has been mounted)	true
usePortal	false true Boolean to control whether or not to render the Popover in a React Portal. Rendering content inside a Portal allows the Popover to escape the bounds of its parent while still being positioned correctly. Using a Portal is necessary if an ancestor of the Popover hides overflow.	true

Content guidelines

Use an interactive element such as button for Popover.Trigger

We strongly recommend using an interactive element such as "button" for "Popover.Trigger", but if you need to use a non-interactive element, like "div", you should make that element focusable by providing "tabindex='0'".

Accessibility

If the popover contains interactive elements that user can navigate through with Tab, consider using react-focus-lock to trap the focus within Popover
When the popover is opened, focus is moved to the Popover.Content. If you set autoFocusto false, it will not move the focus.
When the popover is open and focus is within the Popover.Content, click on Esc key will close the popover. If you set closeOnEsc to false, it will not close.
When the popover is open and focus is within the Popover.Content, click outside popover or blurring out will close the it. If you set closeOnBlur to false, it will not close.
All the necessary a11y attributes for Popover.Content and Popover.Trigger are provided.

Popover

How to use Popover

Import

Examples

Basic

Trapping focus within Popover

Props (API reference)

Name

Type

Default

Content guidelines

Accessibility

Help improve this page