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"
/>#Long content
When the content of a popover is lengthy, consider using a scrollable container to accommodate the text, ensuring that the popover remains a manageable size. Internally, the Popover dynamically adjusts the maximum height of the content area based on the viewport size. One can leverage, for instance, the overflowY: "auto" and maxHeight: "inherit" CSS properties to make the inner content scrollable on viewports with limited height. Moreover, if you want to limit the height of a popover regardless of the viewport size, consider setting maxHeight to a specific value, such as rem or vh, to maintain consistent sizing across different screen dimensions.
<Popover
popoverContent={(id) => (
<Content
id={id}
style={{
overflowY: "auto",
maxHeight: "inherit",
}}
>
<Paragraph>
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed commodo quam ac urna laoreet,
ut venenatis magna sodales. Fusce consequat eget tortor ac luctus. Donec libero urna,
facilisis quis tristique vel, sollicitudin nec ligula. Nullam bibendum dolor urna, vitae
pretium urna faucibus eu. Fusce tempor quam dolor, id porttitor est commodo id. Nullam at
laoreet arcu, nec sodales ligula. Vestibulum lacinia feugiat nunc, id molestie elit
feugiat dictum. Aliquam posuere ultricies sem, ut vehicula mi lobortis eget. Duis ac leo
ante. Vestibulum ornare libero interdum, tincidunt nunc at, vulputate urna. Sed rutrum
arcu cursus nisi ullamcorper, elementum congue sapien eleifend.
</Paragraph>
<Paragraph>
Mauris nec viverra lorem. Morbi ut dui vel enim volutpat faucibus sed nec nibh. Ut quis
porttitor elit, ut posuere tortor. Duis placerat blandit odio, ac sodales neque.
Vestibulum dui ex, feugiat facilisis nunc non, placerat varius urna. Vivamus mauris dolor,
scelerisque at enim non, pulvinar porttitor lectus. Phasellus scelerisque quam vel quam
elementum, ut pulvinar sapien fringilla. Integer et leo bibendum quam accumsan euismod.
</Paragraph>
<Paragraph>
Duis suscipit, nisl et tempus mollis, lacus metus aliquam lorem, ac euismod tortor urna at
sem. Nullam accumsan iaculis lacus, eget egestas mauris posuere ut. Suspendisse potenti.
Etiam vitae justo lacinia, dapibus lorem non, ullamcorper augue. Pellentesque finibus
sagittis libero, non venenatis turpis rhoncus dictum. Quisque vulputate dolor dui, at
tincidunt odio tincidunt sit amet. Morbi nibh libero, porta sit amet aliquam vel, pretium
id ipsum.
</Paragraph>
<Paragraph>
Ut vel rutrum elit, nec mattis ante. Orci varius natoque penatibus et magnis dis
parturient montes, nascetur ridiculus mus. Sed efficitur quis augue ut bibendum. Curabitur
consequat, est at accumsan aliquam, arcu arcu gravida sapien, eget fringilla ipsum nunc
sit amet orci. Proin et semper elit. Quisque ultricies arcu id ligula ullamcorper,
tincidunt sodales est hendrerit. Mauris pretium nibh in velit fermentum euismod.
</Paragraph>
<Paragraph>
Phasellus varius leo odio. Vivamus porta bibendum quam eget finibus. Phasellus iaculis
pretium justo laoreet rutrum. Ut sollicitudin dictum odio vel varius. Proin lacinia
efficitur quam, eget facilisis tortor pellentesque in. Praesent blandit tellus in massa
vehicula, vitae hendrerit nisi dictum. Fusce id pellentesque arcu, vitae accumsan nunc.
</Paragraph>
</Content>
)}
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