Search docs

Popover

A small panel that opens next to a button, such as settings or filters.

There is no WAI-ARIA APG pattern for popovers. Popover is a non-modal dialog attached to a button: the page stays usable, and the popover closes when the user moves on.

import { component$, useStyles$ } from '@builder.io/qwik';
import { Popover } from '@leve-ui/popover';
import { LuX } from '@qwikest/icons/lucide';
import styles from './default.css?inline';

export default component$(() => {
  useStyles$(styles);

  return (
    <Popover.Root class="popover-default">
      <Popover.Trigger class="popover-default-trigger">Dimensions</Popover.Trigger>
      <Popover.Content sideOffset={8} class="popover-default-content">
        <Popover.Title class="popover-default-title">Dimensions</Popover.Title>
        <Popover.Description class="popover-default-description">
          Set the size of the layer.
        </Popover.Description>
        <label class="popover-default-label">
          Width
          <input class="popover-default-input" name="width" value="320px" />
        </label>
        <label class="popover-default-label">
          Height
          <input class="popover-default-input" name="height" value="240px" />
        </label>
        <Popover.Close class="popover-default-close" aria-label="Close">
          <LuX class="popover-default-icon" aria-hidden="true" />
        </Popover.Close>
        {/* The library positions the arrow along the edge and sets data-side */}
        <Popover.Arrow class="popover-default-arrow" />
      </Popover.Content>
    </Popover.Root>
  );
});

Installation#

Install the individual package, or use @leve-ui/core to get every component at once:

pnpm add @leve-ui/popover

Anatomy#

import { Popover } from '@leve-ui/popover'; // or '@leve-ui/core'

<Popover.Root>
  <Popover.Anchor /> {/* optional */}
  <Popover.Trigger />
  <Popover.Content>
    <Popover.Title />
    <Popover.Description />
    <Popover.Close />
    <Popover.Arrow />
  </Popover.Content>
</Popover.Root>
PartElementDescription
Popover.Root<div>Wraps the parts and holds the open state.
Popover.Trigger<button>The button that opens and closes the popover. Use as to render another element or component.
Popover.Anchor<div>Optional. The element to place the popover next to, instead of the Trigger. Use as to render another element or component.
Popover.Content<div>The panel, a popover="manual" element in the top layer.
Popover.Arrow<div>Optional. An arrow pointing at the Trigger, drawn with CSS.
Popover.Title<h2>The title that names the popover.
Popover.Description<p>The description of the popover.
Popover.Close<button>A button that closes the popover. Use as to render another element or component.

A component passed to as on Popover.Trigger, Popover.Anchor, or Popover.Close must spread the props it receives onto a single element, including id, aria-*, data-*, and on*$ event handlers.

Popover.Content is rendered where you place it and shown in the top layer, so overflow: hidden and z-index of its ancestors do not clip it. It is positioned next to the Trigger with Floating UI: set side, align and the offsets on the Content, and it flips and shifts to stay in the viewport.

Examples#

Anchor#

Popover.Anchor places the popover next to another element than the Trigger. Here, the filters open below the whole search field, and --leve-popover-anchor-width makes them as wide as the field.

API Reference#

Root#

PropDefaultType
ids–{ trigger?: string; anchor?: string; content?: string; title?: string; description?: string }

Overrides the element IDs of the parts.

defaultOpenfalseboolean

Whether the popover is open initially (uncontrolled). It opens when the page resumes.

bind:open–Signal<boolean>

A signal with the open state (controlled).

onOpenChange$–QRL<(open: boolean) => void>

Called when the popover opens or closes by a user interaction.

Also accepts all <div> attributes.

Data attributeValue
data-leve-popoverAlways present
data-state"open" | "closed"

Trigger#

PropDefaultType
as'button'keyof HTMLElementTagNameMap | Component<any>

The element or component to render instead of <button>. A component must spread the props it receives onto one element.

Also accepts all <button> attributes.

Data attributeValue
data-leve-popover-triggerAlways present
data-state"open" | "closed"

Anchor#

PropDefaultType
as'div'keyof HTMLElementTagNameMap | Component<any>

The element or component to render instead of <div>. A component must spread the props it receives onto one element.

Also accepts all <div> attributes.

Data attributeValue
data-leve-popover-anchorAlways present

Content#

PropDefaultType
side'bottom''top' | 'right' | 'bottom' | 'left'

The side of the Trigger (or Anchor) to place the popover on. It flips when there is no room.

align'center''start' | 'center' | 'end'

The alignment along that side.

sideOffset0number

The distance from the Trigger in px.

alignOffset0number

The offset along the side in px.

avoidCollisionstrueboolean

Whether to flip and shift the popover to keep it in the viewport.

collisionPadding0number

The padding from the viewport edges when avoiding collisions, in px.

arrowPadding0number

The padding between the arrow and the corners of the popover, in px.

closeOnEscapetrueboolean

Whether Escape closes the popover.

closeOnOutsideClicktrueboolean

Whether a pointer down outside the popover closes it.

Also accepts all <div> attributes.

Data attributeValue
data-leve-popover-contentAlways present
data-state"open" | "closed"
data-sideThe final side after flipping: "top" | "right" | "bottom" | "left"
data-align"start" | "center" | "end"
CSS variableValue
--leve-popover-anchor-widthThe width of the Trigger (or Anchor)
--leve-popover-anchor-heightThe height of the Trigger (or Anchor)
--leve-popover-available-widthThe width available in the viewport
--leve-popover-available-heightThe height available in the viewport

The Content gets inline position, top and left while it is open, since its position depends on the Trigger. It matches :popover-open while shown; use it with @starting-style to animate it. Set display (for example flex) only on :popover-open: on the Content itself, it would override the browser's display: none of the closed popover.

Arrow#

No props of its own. Accepts all <div> attributes.

Data attributeValue
data-leve-popover-arrowAlways present
data-sideThe final side of the Content

The Arrow gets an inline offset along the edge facing the Trigger. Draw it with CSS (for example a rotated square) or an SVG inside it.

Title#

No props of its own. Accepts all <h2> attributes.

Data attributeValue
data-leve-popover-titleAlways present

Description#

No props of its own. Accepts all <p> attributes.

Data attributeValue
data-leve-popover-descriptionAlways present

Close#

PropDefaultType
as'button'keyof HTMLElementTagNameMap | Component<any>

The element or component to render instead of <button>. A component must spread the props it receives onto one element.

Also accepts all <button> attributes.

Data attributeValue
data-leve-popover-closeAlways present
data-state"open" | "closed"

Accessibility#

  • Popover.Content renders role="dialog", aria-labelledby pointing to Popover.Title and aria-describedby pointing to Popover.Description. Without a Title, name it with aria-label.
  • Popover.Trigger renders aria-haspopup="dialog", aria-expanded and aria-controls pointing to the Content.
  • When the popover opens, focus moves to its first focusable element (or to the Content). Escape and Popover.Close close it and return focus to the Trigger.
  • Clicking outside the popover or moving focus out of it with Tab closes it, and focus stays where the user moved it.
  • Popover.Arrow is hidden from assistive technologies with aria-hidden="true".

Keyboard Interactions#

KeyDescription
Enter / SpaceOn the Trigger, opens or closes the popover.
TabMoves focus through the popover. Leaving it closes the popover.
EscapeCloses the popover and returns focus to the Trigger, unless closeOnEscape is false.