Skip to content
lab components / Overlay

Popover

Allow users to view additional information or actions relevant to a specific element within a floating container anchored to the trigger

ExamplesPropertiesGuidelines

This is a Lab component!

That means it doesn't satisfy our definition of done and may be changed or even deleted. For an exact status, please reach out to the Fancy team through the dev_fancy or ux_fancy channels.

import { Popover } from "@siteimprove/fancylab";

#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.

Theme: agentic-ai-2025
<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.

Theme: agentic-ai-2025
<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.

Theme: agentic-ai-2025
<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.

Theme: agentic-ai-2025
<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.

Theme: agentic-ai-2025
<Popover popoverContent={(id, firstFocusableRef, { setIsOpen }) => ( <div id={id}> <Content> <Button onClick={() => setIsOpen(false)} ref={firstFocusableRef}> Close popover </Button> </Content> </div> )} buttonContent="Button" startOpen />

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.

Theme: agentic-ai-2025
<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

Theme: agentic-ai-2025
PropertyDescriptionDefinedValue
popoverContentRequired
functioncontent for popover element over dropdown
buttonContentOptional
elementText and other content for dropdown menu
buttonPropsOptional
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
buttonRefOptional
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

#General

Use Popover to

  • Provide supplemental details or explanations that don't fit within the main interface flow.
  • Offer actions related to an element but not critical enough for primary placement.
  • Reveal additional content in limited space without cluttering the interface.
  • Gradually introduce users to additional features or options.

#Placement

Popover is typically used in the following places:

  • Toolbar: To provide customized views or options related to specific tools or actions.
  • Data Visualizations: To display detailed information about data points on charts or graphs when the user interacts with them.
  • Collaboration Tools: To offer commenting, annotation, or sharing options directly on elements like charts, cards, or text.

#Style

  • Siteimprove Design System: Adhere to Siteimprove's guidelines for color, typography, and spacing. If you are not using a component from Fancy, match the styling of your Popover to existing components for visual consistency.

#Interaction

  • Popovers should open on click or hover (depending on user preferences and device capabilities).
  • Popovers should close when:
    • The user clicks outside the popover.
    • The user interacts with a trigger element for another popover.
    • The user presses the Escape key.

#Do not use when

  • Presenting large amounts of content. Use a Modal instead.
  • Displaying primary actions: Integrate critical actions directly into the main interface.
  • Providing simple explanations. Use a Tooltip for brief tooltips or definitions.
  • Providing option lists: Use a Select component for choosing from a set of options

#Accessibility

#For designers

  • Ensure sufficient color contrast between the popover and its background.

#For developers

This component comes with built-in accessibility, no extra work required.

Explore detailed guidelines for this component: Accessibility Specifications

#Writing

  • Keep content concise and focused.
  • Avoid overwhelming users with excessive information.
  • Use clear, actionable language for buttons and links.