Popover
A Popover is a page overlay triggered by a click that displays additional interactive content.
The Popover component is a non-modal dialog that is commonly used for displaying additional rich content above your UI.
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.
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.
| Property | Default token | Modifiable? |
|---|---|---|
| background-color | color-background-body | No |
| border-width | border-width-10 | No |
| border-color | color-border-weaker | No |
| border-radius | border-radius-20 | No |
| box-shadow | shadow-card | No |
| max-width | size-50 | No |
| padding | space-50 | No |
| padding-left | space-70 | No |
| padding-right | space-70 | No |
| z-index | z-index-80 | No |
yarn add @twilio-paste/popover - or - yarn add @twilio-paste/coreimport {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.
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