Loading...
Skip to main content

Popover

Small, contextual overlays for displaying custom content and information via JavaScript.

Overview

Click the button below to show and close a popover.

<OverlayBox
detail="This is the popover content—make it as long as you want."
title="Popover title"
trigger="click"
>
<Button
theme="secondary"
variant="solid"
>
Toggle popover
</Button>
</OverlayBox>

Things to know when using popovers with OverlayBox:

  • Provide meaningful title and detail content; use detail for the popover body.
  • Specify container="body" to avoid rendering problems in more complex components (like our input groups, button groups, etc).
  • Triggering popovers on hidden elements will not work.
  • Popovers for disabled elements must be triggered on a wrapper element.
  • When triggered from links whose text wraps across multiple lines, popovers will be centered between the links' overall width. Apply white-space: nowrap to the link's styles to avoid this behavior.
  • Unmount OverlayBox together with its trigger so the popover and positioning listeners are cleaned up.
  • Popovers can be triggered thanks to an element inside a shadow DOM.

Pass rich content as React nodes instead of injecting untrusted HTML. React escapes text content by default.

The animation effect of this component is dependent on the prefers-reduced-motion media query.

Keep reading to see how popovers work with some examples.

Examples

Live demo

Titles are set via title and body content is set via detail on OverlayBox.

Use the title prop on OverlayBox, rather than the native title attribute on the trigger, to avoid duplicate browser tooltips.

<OverlayBox
detail="And here’s some amazing content. It’s very engaging. Right?"
title="Popover title"
trigger="click"
>
<Button
theme="secondary"
variant="solid"
>
Toggle popover
</Button>
</OverlayBox>

Placement

Set placement to change the direction. Four options are available: top, right, bottom, and left. Directions are mirrored when using Bootstrap in RTL.

<div className="d-flex flex-wrap gap-3">
<OverlayBox
detail="And here’s some amazing content. It’s very engaging. Right?"
placement="left"
title="Popover on left"
trigger="click"
>
<Button
theme="secondary"
variant="solid"
>
Popover on left
</Button>
</OverlayBox>
<OverlayBox
detail="And here’s some amazing content. It’s very engaging. Right?"
placement="top"
title="Popover on top"
trigger="click"
>
<Button
theme="secondary"
variant="solid"
>
Popover on top
</Button>
</OverlayBox>
<OverlayBox
detail="And here’s some amazing content. It’s very engaging. Right?"
placement="bottom"
title="Popover on bottom"
trigger="click"
>
<Button
theme="secondary"
variant="solid"
>
Popover on bottom
</Button>
</OverlayBox>
<OverlayBox
detail="And here’s some amazing content. It’s very engaging. Right?"
placement="right"
title="Popover on right"
trigger="click"
>
<Button
theme="secondary"
variant="solid"
>
Popover on right
</Button>
</OverlayBox>
</div>

Responsive placement

Change placement at different breakpoints using responsivePlacement={{ md: 'right', lg: 'bottom' }}, where each breakpoint is one of sm, md, lg, xl, or 2xl.

<div className="d-flex flex-wrap gap-3">
<OverlayBox
detail="And here’s some amazing content. It’s very engaging. Right?"
placement="top"
responsivePlacement={{
lg: 'bottom',
md: 'right'
}}
title="Popover title"
trigger="click"
>
<Button
theme="secondary"
variant="solid"
>
Top → md:right → lg:bottom
</Button>
</OverlayBox>
<OverlayBox
detail="And here’s some amazing content. It’s very engaging. Right?"
placement="left"
responsivePlacement={{
lg: 'top'
}}
title="Popover title"
trigger="click"
>
<Button
theme="secondary"
variant="solid"
>
Left → lg:top
</Button>
</OverlayBox>
</div>

Resize your browser to see the popover placement change at different breakpoints.

Custom container

When you have some styles on a parent element that interfere with a popover, you’ll want to specify a custom container so that the popover’s HTML appears within that element instead. This is common in responsive tables, input groups, and the like.

<OverlayBox
container="body"
detail="And here’s some amazing content. It’s very engaging. Right?"
title="Popover title"
trigger="click"
>
<Button
theme="secondary"
variant="solid"
>
Popover in body
</Button>
</OverlayBox>

Another situation where you’ll want to set an explicit custom container are popovers inside a dialog, to make sure that the popover itself is appended to the dialog. This is particularly important for popovers that contain interactive elements – dialogs will trap focus, so unless the popover is a child element of the dialog, users won’t be able to focus or activate these interactive elements.

Popover container

document/component/Document/DialogDemo.tsx
<DialogDemo
id="popoverContainerDialog"
label="Popover inside dialog"
title="Popover container"
>
<OverlayBox
container="#popoverContainerDialog"
detail="This popover stays in the dialog’s top layer."
title="Popover title"
trigger="click"
>
<Button
theme="secondary"
variant="solid"
>
Toggle popover
</Button>
</OverlayBox>
</DialogDemo>

Custom popovers

You can customize the appearance of popovers using CSS variables. We pass a CSS module class through overlayClassName to scope our custom appearance and use it to override some of the local CSS variables.

<OverlayBox
detail="This popover is themed via CSS variables."
overlayClassName="_popover_1wmlc_1"
placement="right"
title="Custom popover"
trigger="click"
>
<Button
theme="secondary"
variant="solid"
>
Custom popover
</Button>
</OverlayBox>

Dismiss on next click

Use the focus trigger to dismiss popovers on the user’s next click of an element other than the toggle element. Clicks and focus inside the popover itself do not dismiss it, so users can select text or use controls in the content.

Dismissing on next click requires specific HTML for proper cross-browser and cross-platform behavior. For an anchor trigger, include a tabindex.

Dismissible popover
<OverlayBox
detail="And here’s some amazing content. It’s very engaging. Right?"
title="Dismissible popover"
trigger="focus"
>
<Button
href="#dismiss-on-next-click"
tabIndex={0}
theme="secondary"
variant="solid"
>
Dismissible popover
</Button>
</OverlayBox>

A shown popover can also be dismissed by pressing the Escape key. As with dropdown menus, a popover shown inside a dialog is dismissed on its own: the first Escape closes the popover and a subsequent one closes the dialog.

Disabled elements

Disabled controls are not interactive, so users cannot hover or click them to trigger a popover. As a workaround, place the control inside a keyboard-focusable wrapper and use that wrapper as the OverlayBox trigger.

For disabled popover triggers, you may also prefer trigger={["hover", "focus"]} so that the popover appears as immediate visual feedback to your users as they may not expect to click on a disabled element.

<OverlayBox
detail="Disabled popover"
title="Disabled popover"
trigger={[
'hover',
'focus'
]}
>
<span
className="d-inline-block rounded-3"
tabIndex={0}
>
<Button
disabled
theme="primary"
variant="solid"
>
Disabled button
</Button>
</span>
</OverlayBox>

CSS

Variables

Local CSS custom properties expose the component’s colors, spacing, borders, and transitions. Override them through style or a CSS module. The defaults below come from the Bootstrap stylesheet used by Idea React; see the upstream variable reference.

VariableDefault
--bs-popover-zindexvar(--bs-z-popover)
--bs-popover-max-width280px
--bs-popover-font-sizevar(--bs-font-size-sm)
--bs-popover-bgvar(--bs-bg-body)
--bs-popover-border-widthvar(--bs-border-width)
--bs-popover-border-colorvar(--bs-border-color-translucent)
--bs-popover-border-radiusvar(--bs-radius-7)
--bs-popover-inner-border-radiuscalc(var(--bs-radius-7) - var(--bs-border-width))
--bs-popover-box-shadowvar(--bs-box-shadow)
--bs-popover-header-padding-xvar(--bs-spacer)
--bs-popover-header-padding-yvar(--bs-spacer-3)
--bs-popover-header-font-sizevar(--bs-font-size-sm)
--bs-popover-header-colorinherit
--bs-popover-header-bgvar(--bs-bg-1)
--bs-popover-body-padding-xvar(--bs-spacer)
--bs-popover-body-padding-yvar(--bs-spacer-3)
--bs-popover-body-colorvar(--bs-fg-body)
--bs-popover-arrow-width1rem
--bs-popover-arrow-height0.5rem
--bs-popover-arrow-bordervar(--bs-popover-border-color)
--bs-popover-transition-propertyopacity
--bs-popover-transition-duration0.15s
--bs-popover-transition-timinglinear

Usage

Keep popovers accessible to keyboard and assistive technology users by only adding them to HTML elements that are traditionally keyboard-focusable and interactive (such as links or form controls). While other HTML elements can be made focusable by adding tabIndex={0}, this can create annoying and confusing tab stops on non-interactive elements for keyboard users, and most assistive technologies currently do not announce popovers in this situation. Additionally, do not rely solely on hover as the trigger for your popovers as this will make them impossible to trigger for keyboard users.

Avoid adding an excessive amount of rich content in popovers. Once popovers are displayed, their content is tied to the trigger element with the aria-describedby attribute, causing all of the popover’s content to be announced to assistive technology users as one long, uninterrupted stream.

Popovers do not manage keyboard focus order, and their placement can be random in the DOM, so be careful when adding interactive elements (like forms or links), as it may lead to an illogical focus order or make the popover content itself completely unreachable for keyboard users. In cases where you must use these elements, consider using a dialog instead.

Options

OverlayBox propDefaultDescription
titlerequiredPopover heading as a React node.
detail—Popover body as a React node. Without it, OverlayBox renders a tooltip.
triggerhover and focusUse "click" for the click-to-toggle examples, "focus" to dismiss on blur, or an array of triggers.
placement"top"Preferred direction: top, right, bottom, or left.
responsivePlacement—Override direction at named breakpoints.
containeralongside triggerA selector, DOM element, or callback returning an element. Keep dialog overlays in the dialog’s top layer.
delay0Show/hide delay in milliseconds, or { show: 500, hide: 100 }.
offset12Distance from the trigger, or a [crossAxis, mainAxis] pair.
padding8Viewport inset for overflow avoidance.
fliptrueFlip direction when space is constrained.
overlayClassName—Apply a CSS module class to the popover.
Documentation navigation
On this page
On this page