Skip to main content

Popover

Overview​

The Popover component opens a panel of interactive content, such as a filter form or a set of share options, anchored to the element that toggles it.

Reach for it when the content needs to be used, not just read: a form, a list of links, an inline edit. Tooltip is for hover hints and can't hold anything interactive, and Dropdown is a menu of actions with menu roles. A Popover is a non-modal dialog: focus moves into it when it opens and back to its trigger when it closes, and the rest of the page stays usable.


Import​

import { Popover } from '@allxsmith/bestax-bulma';

Usage​

Basic Popover​

Pass the element that opens it as trigger and the panel as children. Popover.Header names the panel, Popover.Body holds the content, and Popover.Close closes it.

function example() {
  const [statuses, setStatuses] = useState(['open']);

  return (
    <Popover trigger={<Button>Filters</Button>}>
      <Popover.Header>Filter rows</Popover.Header>
      <Popover.Body>
        <Checkboxes value={statuses} onChange={setStatuses}>
          <Checkbox value="open">Open</Checkbox>
          <Checkbox value="closed">Closed</Checkbox>
        </Checkboxes>
      </Popover.Body>
      <Popover.Footer>
        <Popover.Close color="primary">Done</Popover.Close>
      </Popover.Footer>
    </Popover>
  );
}

Placement​

position picks the corner the panel opens from: below or above the trigger, lined up with its left or right edge. auto picks the one that keeps the panel in the viewport, preferring below and on the left. A panel that would still run past the left or right edge of the screen keeps its corner and moves sideways just far enough to fit.

<Buttons>
  <Popover
    position="bottom-left"
    ariaLabel="Bottom left"
    trigger={<Button>bottom-left</Button>}
  >
    <Popover.Body>Opens below, on the left edge.</Popover.Body>
  </Popover>
  <Popover
    position="bottom-right"
    ariaLabel="Bottom right"
    trigger={<Button>bottom-right</Button>}
  >
    <Popover.Body>Opens below, on the right edge.</Popover.Body>
  </Popover>
  <Popover
    position="auto"
    ariaLabel="Auto"
    trigger={<Button color="info">auto</Button>}
  >
    <Popover.Body>Opens wherever it fits.</Popover.Body>
  </Popover>
</Buttons>

Rendering into the Body​

An ancestor with overflow: hidden, like the box below, clips a panel that renders in place. appendToBody renders it at the end of the page through Portal, fixed to the viewport next to the trigger. With server rendering, it shows from the first render after hydration.

<Box overflow="hidden">
  <Popover
    appendToBody
    ariaLabel="Portaled"
    trigger={<Button color="primary">appendToBody</Button>}
  >
    <Popover.Body>This panel escapes the box.</Popover.Body>
  </Popover>
</Box>

A ConfigProvider with a portalContainer sends the panel there instead. That keeps a scoped Theme, or a shadow root's styles, which the end of the page is outside of. Without one, a panel opened inside a Modal, or another overlay that takes its popups, goes into it.

Controlled​

Pass open to hold the state yourself. onOpenChange reports every request to change it, from the trigger, Popover.Close, Escape or a press outside, so wiring it to your setter lets all of them work.

function example() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Paragraph mb="3">The popover is {open ? 'open' : 'closed'}.</Paragraph>
      <Popover
        open={open}
        onOpenChange={setOpen}
        ariaLabel="Account"
        trigger={<Button>Account</Button>}
      >
        <Popover.Body>Signed in as [email protected]</Popover.Body>
        <Popover.Footer>
          <Popover.Close>Sign out</Popover.Close>
        </Popover.Footer>
      </Popover>
    </>
  );
}

Without a Header​

A panel with no Popover.Header needs a name of its own: pass ariaLabel.

<Popover ariaLabel="Share" trigger={<Button>Share</Button>}>
  <Popover.Body>
    <UnorderedList>
      <ListItem>
        <Link href="#email">Email</Link>
      </ListItem>
      <ListItem>
        <Link href="#copy">Copy link</Link>
      </ListItem>
    </UnorderedList>
  </Popover.Body>
</Popover>

Letting Tab Leave​

By default Tab and Shift+Tab stay inside the open panel, and Escape or a close button is the way out. Pass trapFocus={false} to let Tab carry on past the panel; the popover stays open until it is dismissed. Focus still moves in on open and back to the trigger on close.

<Popover
  trapFocus={false}
  ariaLabel="Quick note"
  trigger={<Button>Add note</Button>}
>
  <Popover.Body>
    <Input aria-label="Note" placeholder="Type, then Tab onward" />
  </Popover.Body>
</Popover>

Triggers That Aren't Buttons​

Enter and Space open a trigger the browser wouldn't click on its own. An intrinsic element such as a <span> also gets role="button" and a tab stop. A component such as Tag renders its own element, so pass those two yourself.

<Popover
  ariaLabel="Label help"
  trigger={
    <Tag color="info" role="button" tabIndex={0}>
      What is this?
    </Tag>
  }
>
  <Popover.Body>Labels group rows. Click one to filter by it.</Popover.Body>
</Popover>

Compound (dot-notation) usage​

PopoverHeader, PopoverBody, PopoverFooter and PopoverClose are also available as Popover.Header, Popover.Body, Popover.Footer and Popover.Close, so the whole panel can be composed from the single Popover import.

<Popover trigger={<Button>Rename</Button>}>
  <Popover.Header>Rename file</Popover.Header>
  <Popover.Body>
    <Input aria-label="File name" defaultValue="report.pdf" />
  </Popover.Body>
  <Popover.Footer>
    <Popover.Close>Cancel</Popover.Close>
    <Popover.Close color="primary">Save</Popover.Close>
  </Popover.Footer>
</Popover>


Popover or HoverCard?​

A Popover and a HoverCard both open a panel against a trigger, and a Popover on a small trigger such as a Tag can look a lot like a HoverCard. They work differently:

  • How it opens: a Popover opens and closes when its trigger is clicked or tapped, or gets Enter or Space. A HoverCard opens when the pointer rests on its trigger or keyboard focus lands on it, and a click on the trigger just does what the trigger does.
  • Focus: opening a Popover moves focus into the panel, Tab stays inside it until it closes unless you pass trapFocus={false}, and closing hands focus back to the trigger. A HoverCard moves no focus and traps none: rendered in place, the card comes right after its trigger in the Tab order, and tabbing past its links closes it.
  • What goes in it: a Popover is a dialog for content people work with, such as a form, a set of options or an inline edit. A HoverCard previews what's behind its trigger: something to read, with a link or a button at most, and nothing people can't also reach from the trigger.
  • On touch: a tap opens and closes a Popover the way a click does, and a tap outside closes it. A touch screen doesn't open a HoverCard at all unless you pass openOnTap, which is for a trigger with no tap action of its own.

If people open it to do something, use a Popover. If it shows what they'd find by following the trigger, use a HoverCard.


Accessibility​

Popover follows the WAI-ARIA dialog pattern for a non-modal dialog:

  • The panel is a role="dialog" without aria-modal. It is named by its Popover.Header through aria-labelledby, or by ariaLabel, which takes precedence. A development build warns when an open panel has neither.
  • The trigger gets aria-haspopup="dialog", aria-expanded, and aria-controls pointing at the panel while it is open.
  • Opening moves focus to the first control in the panel, or to the panel itself when it has none. Closing hands focus back to the trigger, as long as focus is still in the panel then, so a click that put it somewhere else keeps it there.
  • Tab and Shift+Tab wrap inside the open panel, which the pattern asks of non-modal dialogs too. Pointer focus, the screen reader's reading cursor and the rest of the page stay free: nothing outside is hidden or made inert, and the page still scrolls. trapFocus={false} lets Tab leave.
  • Escape closes the popover while focus is in the panel or on the trigger. A dialog nested inside the panel, such as a date picker's calendar or another popover, takes its own Escape first.
  • Enter and Space toggle a trigger the browser doesn't click on its own.
  • The open animation is turned off under prefers-reduced-motion: reduce.
  • On a right-to-left page a popover with no position lines its right edge up with the trigger's, so a trigger at the start of the line doesn't push the panel off the screen. A position you pass stays physical: bottom-left lines up the left edges on either page.
  • A panel that would run past the left or right edge of the screen, as on a phone with the trigger mid-row, keeps its corner and moves sideways just far enough to fit, or, wider than the screen, to the edge its text starts from.

  • Tooltip: A hover and focus hint for content nobody needs to interact with.
  • HoverCard: A preview on a link or a button that opens on hover or keyboard focus, without taking focus.
  • Dropdown: A menu of actions, with menu roles and arrow-key navigation.
  • ContextMenu: A menu of actions that opens where you right-click an element, or long press it.
  • Modal: A modal overlay that blocks the page behind it.
  • Portal: What appendToBody renders through.
  • useFocusTrap: The focus trap the panel uses.
  • Helper Props: Bulma helper props for spacing, color, etc.

Additional Resources​


Props​

PropTypeDefaultDescription
triggerReact.ReactElement—Required. The element that opens and closes the popover, such as a Button. Popover gives it aria-haspopup="dialog", aria-expanded, aria-controls while the panel is open, and click and key handlers that run after its own (call preventDefault() in yours to keep the popover from toggling). It has to be a single element that passes onClick and onKeyDown to its DOM node. Enter and Space toggle a trigger the browser doesn't click on its own, and an intrinsic element that isn't already a control (a <span>) also gets role="button" and tabIndex={0} unless it sets them; a component that renders one has to take those itself.
childrenReact.ReactNode—The panel's content, usually Popover.Header, Popover.Body and Popover.Footer.
openboolean—Controlled open state. When set, the trigger and every dismissal only report through onOpenChange.
defaultOpenbooleanfalseInitial open state when uncontrolled. Opening moves focus into the panel, so a popover that starts open takes focus once the page loads.
onOpenChange(open: boolean) => void—Called with the state asked for: true from the trigger opening it, false from the trigger, Popover.Close, Escape or an outside pointerdown. Fires in both controlled and uncontrolled use.
position'bottom-left' | 'bottom-right' | 'top-left' | 'top-right' | 'auto''bottom-left'Where the panel opens against the trigger. Left out, it opens below and lines up with the trigger's start edge, which is its right edge on a right-to-left page, so a trigger at the start of the line doesn't push the panel off the screen. A corner you pass stays physical, so bottom-left lines up the left edges on either page. A panel that would run past the viewport's left or right edge keeps its corner and moves sideways, just far enough to fit or, wider than the viewport, to the edge its text starts from.
appendToBodybooleanfalseRender the panel through Portal, into the portalContainer a ConfigProvider sets, else the overlay it's in that takes its popups, such as a Modal, else document.body, fixed to the viewport, so an ancestor's overflow, transform or stacking context can't clip it. The panel then shows from the commit after hydration, never in server markup. Theming variables set on an ancestor of the trigger reach it only when its container is inside that ancestor.
trapFocusbooleantrueKeep Tab and Shift+Tab inside the panel while it is open, as the ARIA dialog pattern does for a non-modal dialog. Pointer focus leaves freely and the page stays usable. With false, Tab moves past the panel and the popover stays open. Focus moves into the panel on open and back to the trigger on close either way.
closeOnClickOutsidebooleantrueClose on a pointerdown outside the trigger and the panel. Content the panel renders through a portal (a nested Popover, a portaled picker) still counts as inside.
closeOnEscapebooleantrueClose on Escape while focus is in the panel or on the trigger. A dialog nested in the panel, such as a date picker's calendar, takes its own Escape first, and so does content that calls preventDefault() on it.
ariaLabelstring—The panel's accessible name. Without it the panel is named by its Popover.Header, and a development build warns when it has neither.
contentClassNamestring—Additional classes for the panel (.popover-content).
classNamestring—Additional classes for the wrapper around the trigger. The panel takes contentClassName.
...All standard <div> attributes and Bulma helper props—See Helper Props

Subcomponents:

  • Popover.Header: The popover's title, which names the panel for assistive technology.
  • Popover.Body: The popover's main content area.
  • Popover.Footer: A row of actions along the bottom of the popover, aligned to the end.
  • Popover.Close: A Button that closes the popover, handing focus back to the trigger.

Popover.Header​

PropTypeDefaultDescription
classNamestring—Additional CSS classes.
...All standard <div> attributes and Bulma helper props—See Helper Props

Popover.Body​

PropTypeDefaultDescription
classNamestring—Additional CSS classes.
...All standard <div> attributes and Bulma helper props—See Helper Props

Popover.Footer​

PropTypeDefaultDescription
classNamestring—Additional CSS classes.
...All standard <div> attributes and Bulma helper props—See Helper Props

Popover.Close​

PropTypeDefaultDescription
color'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger' | 'white' | 'light' | 'dark' | 'black' | 'text' | 'ghost'—Bulma color variant for the button. ghost renders a link-like button; text renders a minimal text-only button.
size'small' | 'normal' | 'medium' | 'large'—Size of the button.
isLightbooleanfalseApplies the light variant of a colored button, such as primary's. Bulma gives the grayscale colors none, so with no color, or with white or black, isLight gives the light button, as color="light" does, and light or dark with isLight looks the same as without it.
isRoundedbooleanfalseMakes the button rounded.
isLoadingbooleanfalseDisplays a loading spinner, with everything inside the button hidden behind it, in forced colors (Windows' contrast themes) too, and holds the button still: a click, Enter or Space does nothing, so onClick doesn't run, a submit button doesn't submit its form and a click on a link doesn't follow its href, until it's cleared. A custom as component gets that dropped click as its onClick, so it holds still as far as it acts through it. Set it while an action is in progress, so nobody sends it twice. The button carries aria-busy and aria-disabled meanwhile, so a screen reader can tell it won't respond, and stays focusable, so focus isn't lost, with Bulma's focus outline showing it from the keyboard. Under prefers-reduced-motion: reduce the spinner stops and stays drawn. Bulma alone stops only the pointer, hides only the label and takes away the shadow that shows a focused button, so the rest of the look needs bestax's CSS loaded.
isStaticbooleanfalseDraws Bulma's static look and stops the pointer. It doesn't change the element: a <button> with it is still a tab stop that a screen reader announces as a button and Enter and Space press, and in a form it's a submit button. A label that does nothing, such as "@gmail.com" beside an input in a Field with addons, is a Button rendered as="span", which Tab skips and a screen reader reads as text.
isFullwidthbooleanfalseMakes the button full-width.
isFullWidthbooleanfalseDeprecated. Use isFullwidth instead — isFullwidth wins if both are set. Makes the button full-width.
isOutlinedbooleanfalseApplies outlined styling (requires color). On the dark scheme, bestax's stylesheets draw the label and border at the lightness Bulma picks for the color's text on the page wherever that's lighter, so a dark color reads there. On a surface that stays light on both schemes, give the surface Bulma's theme-light class (with the class prefix in a prefixed build), which keeps what's inside it on the light scheme's values.
isInvertedbooleanfalseApplies inverted styling (requires color).
isFocusedbooleanfalseApplies focused styling (visual only).
isActivebooleanfalseApplies active styling (visual only), with no aria-pressed. For a button that stays pressed, use ToggleButton.
isHoveredbooleanfalseApplies hovered styling (visual only).
isDisabledbooleanfalseApplies disabled styling.
classNamestring—Custom class name.
textColorBulma color | 'inherit' | 'current'—Text color helper.
bgColorBulma color | 'inherit' | 'current'—Background color helper.
childrenReact.ReactNode—Button content.
type'button' | 'submit' | 'reset''button'Button type. Defaults to 'button', so a close button inside a form doesn't submit it.
onClickReact.MouseEventHandler<HTMLButtonElement>—Runs before the popover closes. Call preventDefault() to keep it open.
...All standard <button> attributes and Bulma helper props—See Helper Props

CSS & Sass Variables​

Popover registers these variables on its constituent elements, where the themed declarations live. A value set via className, the style prop, or any ancestor is only inherited and loses to the element's own declaration — override by targeting the declaring element in your CSS. See Theme.

CSS VariableSass VariableDefault
--bulma-popover-z-index$popover-z-index30
--bulma-popover-background$popover-backgroundvar(--bulma-scheme-main)
--bulma-popover-color$popover-colorvar(--bulma-text)
--bulma-popover-border-color$popover-border-colorvar(--bulma-border-weak)
--bulma-popover-radius$popover-radiusvar(--bulma-radius-large)
--bulma-popover-shadow$popover-shadowvar(--bulma-shadow)
--bulma-popover-min-width$popover-min-width12rem
--bulma-popover-max-width$popover-max-widthmin(24rem, calc(100vw - 2rem))
--bulma-popover-offset$popover-offset0.25rem
--bulma-popover-header-padding$popover-header-padding0.75rem 1rem
--bulma-popover-header-color$popover-header-colorvar(--bulma-text-strong)
--bulma-popover-header-weight$popover-header-weightvar(--bulma-weight-semibold)
--bulma-popover-body-padding$popover-body-padding1rem
--bulma-popover-footer-padding$popover-footer-padding0.75rem 1rem
--bulma-popover-footer-gap$popover-footer-gap0.5rem
--bulma-popover-animation-duration$popover-animation-duration0.15s