Components
Popover
Interactive floating content anchored to a trigger.
Popover displays interactive content near a trigger. Use it for filters, forms, settings, inline
help, and other content that needs more room than a tooltip.
The component is built on Base UI Popover. Base UI owns positioning, collision handling, dismissal, and focus management; Orkest UI owns the visual design and public API.
Import the components from @orkest/ui/client.
Basic usage#
import { Stack } from '@orkest/ui';
import {
Field,
FieldLabel,
Input,
Popover,
PopoverClose,
PopoverContent,
PopoverDescription,
PopoverPortal,
PopoverPositioner,
PopoverTitle,
PopoverTrigger,
} from '@orkest/ui/client';
export function Example() {
return (
<Popover>
<PopoverTrigger>Open filters</PopoverTrigger>
<PopoverPortal>
<PopoverPositioner>
<PopoverContent width="20rem">
<Stack gap={3}>
<Stack gap={1}>
<PopoverTitle>Filters</PopoverTitle>
<PopoverDescription>
Narrow the result list without leaving the page.
</PopoverDescription>
</Stack>
<Field>
<FieldLabel>Search</FieldLabel>
<Input placeholder="Project name" />
</Field>
<PopoverClose>Done</PopoverClose>
</Stack>
</PopoverContent>
</PopoverPositioner>
</PopoverPortal>
</Popover>
);
}Anatomy#
Popoverowns the open state.PopoverTriggertoggles the popover. It renders a secondary Button by default.PopoverPortalmoves the popover to the document body.PopoverPositionerpositions the content and handles viewport collisions.PopoverContentis the interactive surface. Its children scroll inside the surface.PopoverArrowadds an optional arrow. Keep it as a direct child ofPopoverContentso it stays outside the scrollable body and animates with the surface.PopoverTitleandPopoverDescriptionprovide the accessible name and description.PopoverClosecloses the popover and renders a secondary Button by default.
Positioning and arrow#
PopoverPositioner defaults to side="bottom", align="center", and sideOffset={8}. Override the
side, alignment, and offsets when the trigger needs a different layout.
import { Stack } from '@orkest/ui';
import {
Popover,
PopoverArrow,
PopoverContent,
PopoverDescription,
PopoverPortal,
PopoverPositioner,
PopoverTitle,
PopoverTrigger,
} from '@orkest/ui/client';
export function Example() {
return (
<Popover>
<PopoverTrigger variant="outline">Open on the right</PopoverTrigger>
<PopoverPortal>
<PopoverPositioner side="right" align="start" sideOffset={12}>
<PopoverContent maxWidth="18rem">
<PopoverArrow />
<Stack gap={2}>
<PopoverTitle>Positioned content</PopoverTitle>
<PopoverDescription>
This popover prefers the right side and aligns to the trigger start.
</PopoverDescription>
</Stack>
</PopoverContent>
</PopoverPositioner>
</PopoverPortal>
</Popover>
);
}Controlled state#
import { useState } from 'react';
import { Stack, Text } from '@orkest/ui';
import {
Popover,
PopoverClose,
PopoverContent,
PopoverDescription,
PopoverPortal,
PopoverPositioner,
PopoverTitle,
PopoverTrigger,
} from '@orkest/ui/client';
export function Example() {
const [open, setOpen] = useState(false);
return (
<Stack direction="row" gap={3} wrap align="center">
<Popover open={open} onOpenChange={setOpen}>
<PopoverTrigger>Toggle popover</PopoverTrigger>
<PopoverPortal>
<PopoverPositioner>
<PopoverContent maxWidth="18rem">
<Stack gap={2}>
<PopoverTitle>Controlled popover</PopoverTitle>
<PopoverDescription>
The parent owns the open state.
</PopoverDescription>
<PopoverClose>Close</PopoverClose>
</Stack>
</PopoverContent>
</PopoverPositioner>
</PopoverPortal>
</Popover>
<Text size="sm" tone="muted">
{open ? 'Status: open' : 'Status: closed'}
</Text>
</Stack>
);
}Dialog semantics#
PopoverContent renders role="dialog" by default and uses PopoverTitle and
PopoverDescription for aria-labelledby and aria-describedby. When the content is not a dialog,
pass a different role such as region or group:
<PopoverContent role="region">{/* ... */}</PopoverContent>Use dialog semantics when the content has a clear title and behaves like a small dialog. Use a region or group for lightweight inline help.
Sizing and scrolling#
PopoverContent fits its content by default, has a maximum width of 25rem, and scrolls when it
exceeds the available viewport height. Use width, minWidth, maxWidth, and maxHeight for
specific layouts.
import { Stack, Text } from '@orkest/ui';
import {
Popover,
PopoverClose,
PopoverContent,
PopoverPortal,
PopoverPositioner,
PopoverTrigger,
} from '@orkest/ui/client';
export function Example() {
return (
<Popover>
<PopoverTrigger variant="outline">Show inline help</PopoverTrigger>
<PopoverPortal>
<PopoverPositioner>
<PopoverContent role="region" maxWidth="18rem">
<Stack gap={2}>
<Text size="sm" weight="medium">Keyboard shortcuts</Text>
<Text as="p" size="sm" tone="muted">
Press ⌘K to search. Use arrow keys to move between results.
</Text>
<PopoverClose>Got it</PopoverClose>
</Stack>
</PopoverContent>
</PopoverPositioner>
</PopoverPortal>
</Popover>
);
}Accessibility#
PopoverTriggershould have a clear accessible name. The default Button uses its children.- Focus moves into the content when the popover opens and returns to the trigger when it closes.
- Escape and outside pointer presses close the popover by default.
- Use
PopoverTitlefor the accessible name andPopoverDescriptionfor supporting text. - Use dialog semantics for dialog-like content and a region or group for lightweight content.
PopoverContentcan contain forms, buttons, and other interactive components.- The arrow is decorative and does not affect the accessible name.
- The popover respects
prefers-reduced-motionfor its open and close animation.
Props#
Popover#
| Prop | Type | Default |
|---|---|---|
open | boolean | — |
| Controlled open state. | ||
defaultOpen | boolean | false |
| Initial open state for uncontrolled usage. | ||
onOpenChange | (open, eventDetails) => void | — |
| Called when the popover requests an open state change. | ||
modal | boolean | 'trap-focus' | false |
| Optionally limits interaction to the popover or traps focus. | ||
onOpenChangeComplete | (open: boolean) => void | — |
| Called after the open or close animation completes. | ||
actionsRef | RefObject<{ close: () => void; unmount: () => void }> | — |
| Imperative close and unmount actions. | ||
PopoverTrigger and PopoverClose#
| Prop | Type | Default |
|---|---|---|
variant | 'primary' | 'secondary' | 'outline' | 'ghost' | 'destructive' | 'link' | Trigger: 'secondary'; Close: 'secondary' |
| Visual Button variant used by the default button. | ||
render | ReactElement | — |
| Replaces the default Button with a custom element. | ||
openOnHover / delay / closeDelay | boolean / number / number | false / 300 / 0 |
| Optionally opens the popover when the trigger is hovered. | ||
PopoverPositioner#
| Prop | Type | Default |
|---|---|---|
side | 'top' | 'bottom' | 'left' | 'right' | 'inline-start' | 'inline-end' | 'bottom' |
| Side of the trigger the popover is placed on. | ||
align | 'start' | 'center' | 'end' | 'center' |
| Alignment relative to the trigger. | ||
sideOffset | number | 8 |
| Distance between the trigger and the popover. | ||
alignOffset | number | 0 |
| Offset along the alignment axis. | ||
collisionPadding | number | Partial<Record<side, number>> | — |
| Keeps the popover away from viewport edges. | ||
PopoverContent#
| Prop | Type | Default |
|---|---|---|
role | AriaRole | 'dialog' |
| ARIA role. Use region or group for non-dialog content. | ||
width / minWidth / maxWidth | CSSProperties values | — |
| Controls surface width. The default maximum is 25rem. | ||
maxHeight | CSSProperties value | — |
| Controls the scrolling threshold. | ||
initialFocus / finalFocus | boolean | RefObject | function | — |
| Controls focus entry and return. | ||
native attributes | Base UI Popover Popup props | — |
| Class names, data attributes, and refs are forwarded to the popup. | ||
Related#
- Tooltip for short, non-interactive hints.
- Dialog for modal tasks and forms.
- Dropdown Menu for command menus.