Popover
Display additional information or actions relevant to a specific element, appearing as 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