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.
Dimensions
Set the size of the layer.
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>
);
});.popover-default-trigger {
padding: 8px 14px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
font: inherit;
font-size: 14px;
font-weight: 500;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}
.popover-default-trigger:hover {
background: light-dark(#f1f5f9, #ffffff14);
}
/* The Content is a popover in the top layer; the library sets its position */
.popover-default-content {
box-sizing: border-box;
width: 260px;
padding: 16px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
font-family: inherit;
box-shadow: 0 8px 24px rgb(15 23 42 / 0.18);
overflow: visible;
}
.popover-default-content:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.popover-default-title {
margin: 0;
font-size: 15px;
font-weight: 600;
}
.popover-default-description {
margin: 4px 0 12px;
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
}
.popover-default-label {
display: grid;
grid-template-columns: 64px 1fr;
align-items: center;
margin-top: 8px;
font-size: 13px;
}
.popover-default-input {
min-width: 0;
padding: 6px 8px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
font: inherit;
color: inherit;
}
.popover-default-close {
position: absolute;
top: 8px;
right: 8px;
display: inline-flex;
padding: 4px;
border: none;
border-radius: 6px;
background: none;
color: light-dark(#475569, #c9ddf0);
cursor: pointer;
}
.popover-default-close:hover {
background: light-dark(#f1f5f9, #ffffff14);
}
.popover-default-icon {
width: 14px;
height: 14px;
}
/* A rotated square half outside the edge facing the Trigger */
.popover-default-arrow {
width: 10px;
height: 10px;
background: inherit;
border: inherit;
rotate: 45deg;
}
.popover-default-arrow[data-side="bottom"] {
margin-top: -6px;
border-right: none;
border-bottom: none;
}
.popover-default-arrow[data-side="top"] {
margin-bottom: -6px;
border-left: none;
border-top: none;
}
.popover-default-trigger:focus-visible,
.popover-default-input:focus-visible,
.popover-default-close:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}Installation#
Install the individual package, or use @leve-ui/core to get every component at once:
pnpm add @leve-ui/popovernpm install @leve-ui/popoveryarn add @leve-ui/popoverbun add @leve-ui/popoverpnpm add @leve-ui/corenpm install @leve-ui/coreyarn add @leve-ui/corebun add @leve-ui/coreAnatomy#
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>
| Part | Element | Description |
|---|---|---|
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.
Filters
import { component$, type PropsOf, Slot, useStyles$ } from '@builder.io/qwik';
import { Popover } from '@leve-ui/popover';
import { LuSlidersHorizontal } from '@qwikest/icons/lucide';
import styles from './anchor.css?inline';
// Custom components passed to `as` must spread all received props onto one element
const FieldWrapper = component$<PropsOf<'div'>>((props) => (
<div {...props}>
<Slot />
</div>
));
const IconButton = component$<PropsOf<'button'>>(({ type = 'button', ...props }) => (
<button type={type} {...props}>
<Slot />
</button>
));
export default component$(() => {
useStyles$(styles);
return (
<Popover.Root class="popover-anchor">
{/* The Content is placed below the whole field, not only below the button */}
<Popover.Anchor as={FieldWrapper} class="popover-anchor-field">
<input class="popover-anchor-input" aria-label="Search" placeholder="Search" />
<Popover.Trigger as={IconButton} class="popover-anchor-trigger" aria-label="Filters">
<LuSlidersHorizontal class="popover-anchor-icon" aria-hidden="true" />
</Popover.Trigger>
</Popover.Anchor>
<Popover.Content align="start" sideOffset={6} class="popover-anchor-content">
<Popover.Title class="popover-anchor-title">Filters</Popover.Title>
<label class="popover-anchor-option">
<input type="checkbox" name="open" checked /> Open issues
</label>
<label class="popover-anchor-option">
<input type="checkbox" name="mine" /> Assigned to me
</label>
</Popover.Content>
</Popover.Root>
);
});.popover-anchor-field {
display: flex;
align-items: center;
width: 280px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
font-family: inherit;
}
.popover-anchor-input {
flex: 1;
min-width: 0;
padding: 8px 10px;
border: none;
background: transparent;
font: inherit;
font-size: 14px;
color: light-dark(#0f172a, #ffffff);
}
.popover-anchor-trigger {
display: inline-flex;
margin: 4px;
padding: 6px;
border: none;
border-radius: 6px;
background: none;
color: light-dark(#475569, #c9ddf0);
cursor: pointer;
}
.popover-anchor-trigger:hover,
.popover-anchor-trigger[data-state="open"] {
background: light-dark(#f1f5f9, #ffffff14);
}
.popover-anchor-icon {
width: 16px;
height: 16px;
}
/* --leve-popover-anchor-width is the width of the Anchor */
.popover-anchor-content {
box-sizing: border-box;
width: var(--leve-popover-anchor-width);
padding: 12px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
font-family: inherit;
box-shadow: 0 8px 24px rgb(15 23 42 / 0.18);
}
.popover-anchor-title {
margin: 0 0 8px;
font-size: 13px;
font-weight: 600;
}
.popover-anchor-option {
display: flex;
align-items: center;
gap: 8px;
padding: 4px 0;
font-size: 14px;
}
.popover-anchor-input:focus-visible,
.popover-anchor-trigger:focus-visible,
.popover-anchor-content:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}API Reference#
Root#
| Prop | Default | Type |
|---|---|---|
| ids | – | { trigger?: string; anchor?: string; content?: string; title?: string; description?: string } Overrides the element IDs of the parts. |
| defaultOpen | false | boolean 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 attribute | Value |
|---|---|
data-leve-popover | Always present |
data-state | "open" | "closed" |
Trigger#
| Prop | Default | Type |
|---|---|---|
| as | 'button' | keyof HTMLElementTagNameMap | Component<any> The element or component to render instead of |
Also accepts all <button> attributes.
| Data attribute | Value |
|---|---|
data-leve-popover-trigger | Always present |
data-state | "open" | "closed" |
Anchor#
| Prop | Default | Type |
|---|---|---|
| as | 'div' | keyof HTMLElementTagNameMap | Component<any> The element or component to render instead of |
Also accepts all <div> attributes.
| Data attribute | Value |
|---|---|
data-leve-popover-anchor | Always present |
Content#
| Prop | Default | Type |
|---|---|---|
| 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. |
| sideOffset | 0 | number The distance from the Trigger in px. |
| alignOffset | 0 | number The offset along the side in px. |
| avoidCollisions | true | boolean Whether to flip and shift the popover to keep it in the viewport. |
| collisionPadding | 0 | number The padding from the viewport edges when avoiding collisions, in px. |
| arrowPadding | 0 | number The padding between the arrow and the corners of the popover, in px. |
| closeOnEscape | true | boolean Whether Escape closes the popover. |
| closeOnOutsideClick | true | boolean Whether a pointer down outside the popover closes it. |
Also accepts all <div> attributes.
| Data attribute | Value |
|---|---|
data-leve-popover-content | Always present |
data-state | "open" | "closed" |
data-side | The final side after flipping: "top" | "right" | "bottom" | "left" |
data-align | "start" | "center" | "end" |
| CSS variable | Value |
|---|---|
--leve-popover-anchor-width | The width of the Trigger (or Anchor) |
--leve-popover-anchor-height | The height of the Trigger (or Anchor) |
--leve-popover-available-width | The width available in the viewport |
--leve-popover-available-height | The 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 attribute | Value |
|---|---|
data-leve-popover-arrow | Always present |
data-side | The 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 attribute | Value |
|---|---|
data-leve-popover-title | Always present |
Description#
No props of its own. Accepts all <p> attributes.
| Data attribute | Value |
|---|---|
data-leve-popover-description | Always present |
Close#
| Prop | Default | Type |
|---|---|---|
| as | 'button' | keyof HTMLElementTagNameMap | Component<any> The element or component to render instead of |
Also accepts all <button> attributes.
| Data attribute | Value |
|---|---|
data-leve-popover-close | Always present |
data-state | "open" | "closed" |
Accessibility#
Popover.Contentrendersrole="dialog",aria-labelledbypointing toPopover.Titleandaria-describedbypointing toPopover.Description. Without a Title, name it witharia-label.Popover.Triggerrendersaria-haspopup="dialog",aria-expandedandaria-controlspointing to the Content.- When the popover opens, focus moves to its first focusable element (or to the Content). Escape and
Popover.Closeclose 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.Arrowis hidden from assistive technologies witharia-hidden="true".
Keyboard Interactions#
| Key | Description |
|---|---|
Enter / Space | On the Trigger, opens or closes the popover. |
Tab | Moves focus through the popover. Leaving it closes the popover. |
Escape | Closes the popover and returns focus to the Trigger, unless closeOnEscape is false. |