Popover
Allow users to view additional information or actions relevant to a specific element within a floating container anchored to the trigger
Examples
Use Popovers sparingly to avoid cluttering the interface and distracting users from their primary tasks. Popover is composed of:
- Trigger Element: The button that, when interacted with, opens the popover. View Button appearance. Consider using descriptive labels or icons for the trigger element to clarify its purpose.
- Popover Container: The floating box that houses the popover content. Ensure sufficient padding and spacing within the container for readability.
- Content Area: The space within the popover for text, icons, links, or other interactive elements. Prioritize the most important information at the top.
- Close Button (optional): A button to dismiss the popover. Place it consistently (e.g., button-right corner) and use a recognizable icon (e.g., "x").
- Footer (optional): Use Action bar for actions or additional information related to the entire popover. Clearly separate the footer from the main content area visually. View Footer variant
Default
The default variant includes a button trigger with a chevron icon, popover content area, and optional close button. Here's an example of a default implementation of the Popover component. Assign the firstFocusableRef property to the first focusable element in the popover.
<Popover
popoverContent={(id, firstFocusableRef, { setIsOpen }) => (
<div id={id}>
<Content>
<Button onClick={() => setIsOpen(false)} ref={firstFocusableRef}>
Close popover
</Button>
</Content>
</div>
)}
buttonContent="Button"
/>Button appearance
Customize the Button's appearance using the ButtonProps property. This allows you to change the button's style, size, and other visual attributes.
<Popover
popoverContent={(id, firstFocusableRef, { setIsOpen }) => (
<div id={id}>
<Content>
<Button onClick={() => setIsOpen(false)} ref={firstFocusableRef}>
Close popover
</Button>
</Content>
</div>
)}
buttonContent="Button"
buttonProps={{ variant: "primary", size: "large" }}
/>Hide the chevron icon using the hideChevron property if it's not needed.
<Popover
aria-label="Edit"
popoverContent={(id, firstFocusableRef, { setIsOpen }) => (
<div id={id}>
<Content>
<Button onClick={() => setIsOpen(false)} ref={firstFocusableRef}>
Close popover
</Button>
</Content>
</div>
)}
buttonContent={
<Icon>
<IconEdit />
</Icon>
}
hideChevron
/>Popover placement
Choose a placement that ensures the popover is visible and doesn't obstruct important content. Use the placement property to control popover positioning relative to the trigger element.
<Popover
popoverContent={(id, firstFocusableRef, { setIsOpen }) => (
<div id={id}>
<Content>
<Button onClick={() => setIsOpen(false)} ref={firstFocusableRef}>
Close popover
</Button>
</Content>
</div>
)}
buttonContent="Button"
placement="top"
/>Start open
Use the startOpen property to display the popover immediately when the page loads. This is generally not recommended for most use cases.
<Popover
popoverContent={(id, firstFocusableRef, { setIsOpen }) => (
<div id={id}>
<Content>
<Button onClick={() => setIsOpen(false)} ref={firstFocusableRef}>
Close popover
</Button>
</Content>
</div>
)}
buttonContent="Button"
startOpen
/>Footer
Popovers can optionally contain a footer. This section is intended for information and actions that relate to the Popover as a whole. In most cases, that will be the Action bar component, which provides users with a set of actions related to the completion of a task.
Add a footer by placing a Popover.Footer component in Popover as its s its last child.
<Popover
popoverContent={(id, firstFocusableRef, { setIsOpen }) => (
<div id={id}>
<Content>
<Button onClick={() => setIsOpen(false)} ref={firstFocusableRef}>
Close popover
</Button>
</Content>
<Popover.Footer>
<ActionBar
primary={{ children: "Primary", onClick: console.log }}
cancel={{ children: "Cancel", onClick: console.log }}
/>
</Popover.Footer>
</div>
)}
buttonContent="Button"
/>Properties
| Property | Description | Defined | Value |
|---|---|---|---|
popoverContentRequired | functioncontent for popover element over dropdown | ||
elementText and other content for dropdown menu | |||
objectProps to affect the styling of the dropdown button | |||
labelledByPopoverOptional | booleanIf set to true, popover label may be set to the id, if isOpen is also true | ||
placementOptional | "auto" | "auto-end" | "auto-start" | "bottom" | "bottom-end" | "bottom-start" | "left" | "left-end" | "left-start" | "right" | "right-end" | "right-start" | "top" | "top-end" | "top-start"Preferred placement for the popover | ||
allowedAutoPlacementsOptional | literal-union[]Allowed placements for the popover when using an "auto" value for the "placement" prop | ||
strategyOptional | "absolute" | "fixed"Position popover using fixed or absolute | ||
objectreference sent to basePopover element | |||
startOpenOptional | booleanIf set to true the dropdown will open automatically | ||
invalidOptional | booleanIs the dropdown in an invalid state | ||
containerClassNameOptional | stringClassname for container of both dropdown and popover | ||
hideChevronOptional | booleanIf set to true, chevron icon will be hidden | ||
noMinWidthOptional | booleanIf true, the default minimum width won't be set | ||
noMaxWidthOptional | booleanIf true, the default maximum width won't be set | ||
disabledOptional | booleanMakes the component non-interactive | ||
aria-labelOptional | stringDescribe what happens if the button is clicked (for icon only buttons) | ||
aria-haspopupOptional | "dialog" | "listbox" | "menu"What type of content is expanded. Should only be set if the content has the corrosponding 'role' | ||
onCloseOptional | functionCallback for onClose events | ||
onClearOptional | functionCallback for clearing the dropdown (displays clear button when provided) | ||
tooltipOptional | | string | number | elementTooltip text | ||
tooltipPlacementOptional | "bottom" | "bottom-end" | "bottom-start" | "left" | "left-end" | "left-start" | "right" | "right-end" | "right-start" | "top" | "top-end" | "top-start"Tooltip placement | ||
updateKeysOptional | unknown[]Key to control updates to the placement of the popover. Provide a different value when an update is desired | ||
data-componentOptional | stringName of the component. Should only be set by components since it needs to stable. Used to track component usage | ||
data-observe-keyOptional | stringUnique string, used by external script e.g. for event tracking | ||
classNameOptional | stringCustom className that's applied to the outermost element (only intended for special cases) | ||
styleOptional | objectStyle object to apply custom inline styles (only intended for special cases) | ||
tabIndexOptional | numberTab index of the outermost HTML element of the component | ||
onKeyDownOptional | functionCallback for onKeyDown event | ||
onMouseDownOptional | functionCallback for onMouseDown event | ||
onMouseEnterOptional | functionCallback for onMouseEnter event | ||
onMouseLeaveOptional | functionCallback for onMouseLeave event | ||
onFocusOptional | functionCallback for onFocus event | ||
onBlurOptional | functionCallback for onBlur event |
Guidelines
Best practices
Do not use when
Accessibility
Explore detailed guidelines for this component: Accessibility Specifications