Skip to content
Change the site theme
Figma
(information)

Popover

Peer review pending

A Popover is a page overlay triggered by a click that displays additional interactive content.


Guidelines

Guidelines page anchor

About Popover

About Popover page anchor

The Popover component is a non-modal dialog that is commonly used for displaying additional rich content above your UI.

Popover compared to Tooltip

Popover compared to Tooltip page anchor

Popovers and non-modal dialogs follow these accessibility guidelines:

  • There must be a focusable element inside the popover.
  • There should be a close button so screen readers have a specific close action to target.
  • A Popover is a focus trap, and focus is placed inside it when it's shown.
  • A Popover must be triggered by an explicit user action, e.g. clicking a button.

The placement of the popover is configurable via the placement prop. The available placement options are available in the props description here.

The Popover's width will grow to fit its content up to a maximum width of our size50 token. Content width can be adjusted, up to the Popover's max width, by wrapping it in a Box component with a declared width.

The PopoverButton renders a Button component and accepts all of its props, which are listed on the Button page.

To launch a Popover from a Badge component, use the PopoverBadgeButton component. It renders a Badge and accepts all of its props except for as, which are listed on the Badge page.

Popover comes with the option of "hooking" into the internal state by using the state hook originally provided by Reakit(link takes you to an external page).

Rather than the state be internal to the component, you can use the usePopoverState hook and pass the returned state to PopoverContainer as the state prop.

This allows you to use certain returned props from the state hook, including functions like hide and show.

An example usecase of this might be programmatically providing the user a popover when a certain user action is taken. In the example below we are showing a popover when another button is pressed. When pressed the button uses the show function from the hook. Another button using the hide function from the hook is also provided to hide the popover when pressed.

It should be noted that when doing so, the state prop takes precedent over the other properties that affect the state or initial state of the Popover. They will be ignored in favour of them being provided as arguments to the usePopoverState hook.

For full details on how to use the state hook, and what props to provide it, follow the Non-Modal Dialog Primitive documentation. It's the same hook, just renamed.

To internationalize the popover, simply pass different text as children to the popover's contents and the aria-label prop. The only exception is the dismiss button–to change the dismiss button’s text, use the i18nDismissLabel prop.

See the button component.

See the badge component.

PropertyDefault tokenModifiable?
background-colorcolor-background-bodyNo
border-widthborder-width-10No
border-colorcolor-border-weakerNo
border-radiusborder-radius-20No
box-shadowshadow-cardNo
max-widthsize-50No
paddingspace-50No
padding-leftspace-70No
padding-rightspace-70No
z-indexz-index-80No

Installation

Installation page anchor
yarn add @twilio-paste/popover - or - yarn add @twilio-paste/core
import {Popover, PopoverContainer, PopoverButton} from '@twilio-paste/core/popover';
const PopoverExample: React.FC = () => {
return (
<PopoverContainer baseId="popover-example">
<PopoverButton variant="primary">Open popover</PopoverButton>
<Popover aria-label="Popover">Popover content</Popover>
</PopoverContainer>
);
};

Pass these as part of an object to the usePopoverState hook.

baseId?: string

Sets the ID that will serve as a base for all the items IDs.

gutter?: string

Sets the offset between the reference and the popover on the main axis.

placement?: "auto-start" | "auto" | "auto-end" | "top-start...

Sets the placement of popover in relation to the NonModalDialogDisclosurePrimitive. Available options include:

  • auto-start
  • auto-end
  • auto
  • top-start
  • top-end
  • top
  • bottom-start
  • bottom-end
  • bottom
  • right-start
  • right-end
  • right
  • left-start
  • left-end
  • left
visible?: boolean

Whether the dialog is visible or not.

animated?: number | boolean

If true, animating will be set to true when visible is updated. It'll wait for stopAnimation to be called or a CSS transition ends. If animated is set to a number, stopAnimation will be called only after the same number of milliseconds have passed.

modal?: boolean

Sets the modal state.

  • Non-modal: preventBodyScroll doesn't work and focus is free.
  • Modal: preventBodyScroll is automatically enabled, focus is trapped within the dialog and the dialog is rendered within a Portal.

usePopoverState returned props

usePopoverState returned props page anchor

These props are returned by the state hook. You can spread them into this component ({...state}) or pass them separately. You can also provide these props from your own state logic.

baseId?: string

Sets the ID that will serve as a base for all the items IDs.

gutter?: string

Sets the offset between the reference and the popover on the main axis.

placement?: "auto-start" | "auto" | "auto-end" | "top-start...

Sets the placement of popover in relation to the NonModalDialogDisclosurePrimitive. Available options include:

  • auto-start
  • auto-end
  • auto
  • top-start
  • top-end
  • top
  • bottom-start
  • bottom-end
  • bottom
  • right-start
  • right-end
  • right
  • left-start
  • left-end
  • left
visible?: boolean

Whether the dialog is visible or not.

animated?: number | boolean

If true, animating will be set to true when visible is updated. It'll wait for stopAnimation to be called or a CSS transition ends. If animated is set to a number, stopAnimation will be called only after the same number of milliseconds have passed.

modal?: boolean

Sets the modal state.

  • Non-modal: preventBodyScroll doesn't work and focus is free.
  • Modal: preventBodyScroll is automatically enabled, focus is trapped within the dialog and the dialog is rendered within a Portal.
animating?: boolean

Whether it's animating or not.

stopAnimation?: () => void

Stops animation. It's called automatically if there's a CSS transition

show?: () => void

Changes the visible state to true.

hide?: () => void

Changes the visible state to false.

baseId?: string

Sets the ID that will serve as a base for all the items IDs.

gutter?: string

Sets the offset between the reference and the popover on the main axis.

placement?: "auto-start" | "auto" | "auto-end" | "top-start...

Sets the placement of popover in relation to the PopoverButton. Available options include:

  • auto-start
  • auto-end
  • auto
  • top-start
  • top-end
  • top
  • bottom-start
  • bottom-end
  • bottom
  • right-start
  • right-end
  • right
  • left-start
  • left-end
  • left
aria-label: string

Required label for this Popover component. Titles the entire popover context for screen readers.

i18nDismissLabel: string

Label for the dismiss button in the popover. The default value is 'Close popover'.

element?: string

Overrides the default element name ('POPOVER') to apply unique styles with the Customization Provider


Black lives matter.