Popover

A clickable floating panel that attaches to a trigger element. Focus traps inside while open; dismisses on outside-click or Escape. Use for action menus, color pickers, settings panels — anything richer than a hover tooltip.

import { Popover, Button } from '@dashforge/tw';

<Popover content={<QuickActions />}>
  <Button>Open</Button>
</Popover>

Popover vs Tooltip vs Menu

Three floating primitives, three different jobs. Pick the right one:

Rough mental model: Tooltip < Popover < Menu in terms of interaction richness.

Quick Start

import { Popover, Button, Stack, Typography } from '@dashforge/tw';

<Popover
  content={
    <Stack gap={2}>
      <Typography variant="subtitle2">Quick actions</Typography>
      <Stack gap={1}>
        <Button variant="ghost" size="sm">Duplicate</Button>
        <Button variant="ghost" size="sm">Share</Button>
        <Button variant="ghost" size="sm" color="danger">Delete</Button>
      </Stack>
    </Stack>
  }
>
  <Button variant="outline">Open popover</Button>
</Popover>

The single child of <Popover> is the trigger — Radix's asChild pattern paints the popover semantics onto it. Wrap any interactive element (<Button>, <IconButton>, <Chip>, or a plain <button>).

Examples

Basic

import { Popover, Button, Stack, Typography } from '@dashforge/tw';

<Popover
  content={
    <Stack gap={2}>
      <Typography variant="subtitle2">Quick actions</Typography>
      <Stack gap={1}>
        <Button variant="ghost" size="sm">Duplicate</Button>
        <Button variant="ghost" size="sm">Share</Button>
        <Button variant="ghost" size="sm" color="danger">Delete</Button>
      </Stack>
    </Stack>
  }
>
  <Button variant="outline">Open popover</Button>
</Popover>

Four-side placement

side selects which edge of the trigger the popover attaches to. align further tunes the perpendicular axis ('start' | 'center' | 'end'). showArrow renders a small pointer for extra clarity.

import { Popover, Button } from '@dashforge/tw';

<Popover side="top"    showArrow content="Popover on top">    <Button>top</Button></Popover>
<Popover side="right"  showArrow content="Popover on right">  <Button>right</Button></Popover>
<Popover side="bottom" showArrow content="Popover on bottom"> <Button>bottom</Button></Popover>
<Popover side="left"   showArrow content="Popover on left">   <Button>left</Button></Popover>

<Popover side="top"    showArrow content="Popover on top">    <Button>top</Button></Popover>
<Popover side="right"  showArrow content="Popover on right">  <Button>right</Button></Popover>
<Popover side="bottom" showArrow content="Popover on bottom"> <Button>bottom</Button></Popover>
<Popover side="left"   showArrow content="Popover on left">   <Button>left</Button></Popover>

Radix auto-flips the side if the requested edge would clip against the viewport — so side="bottom" near the page bottom silently becomes side="top". The align prop follows the same "auto-nudge to fit" behavior.

Controlled state

Omit open/onOpenChange for the default click-to-toggle behavior. Provide them when the popover should be driven externally (a keyboard shortcut, a state machine transition, a route change):

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

<Popover open={open} onOpenChange={setOpen} content={<Panel />}>
  <Button>Trigger</Button>
</Popover>

// Later, from a keyboard shortcut handler:
useHotkey('cmd+k', () => setOpen((o) => !o));

Fixed-width panel

Pass width as any CSS length to constrain the content — useful for form-shaped popovers where you want the panel to keep its shape regardless of body content:

<Popover
  width="320px"
  content={
    <Stack gap={2}>
      <Typography variant="subtitle2">Filter</Typography>
      <TextField name="query" label="Search" />
    </Stack>
  }
>
  <Button>Filter</Button>
</Popover>

Nested content — forms, pickers, settings

Because the popover captures focus, you can put anything interactive inside — including form fields:

<Popover
  content={
    <Stack gap={3} sx="min-w-[280px]">
      <Typography variant="subtitle2">Add label</Typography>
      <TextField name="label" placeholder="e.g. urgent" required />
      <Stack direction="row" gap={2} justify="end">
        <Button variant="outline" size="sm">Cancel</Button>
        <Button color="primary" size="sm">Add</Button>
      </Stack>
    </Stack>
  }
>
  <Button variant="outline">+ Label</Button>
</Popover>

Tab moves focus across the fields inside the popover; Escape dismisses; outside-click dismisses without submitting.

Theme defaults

Configure <Popover> defaults application-wide.

import { patchTheme } from '@dashforge/tw-theme';

patchTheme({
  components: {
    Popover: {
      defaults: { side: 'bottom', align: 'center', sideOffset: 8, showArrow: false },
    },
  },
});

Configurable axes (PopoverVariantProps):

Non-visual axes (children, content, open, onOpenChange, width, slotProps) are per-instance — they carry the popover's identity or per-usage layout.

Precedence chain (lowest → highest):

1. Built-in defaults (side='bottom', align='center', showArrow=false, sideOffset=8).
2. theme.components.Popover.defaults (application-wide).
3. Instance prop (<Popover side="top" showArrow />) — wins over theme.
4. slotProps.content — reaches the floating panel for a targeted class override.

TypeScript: theme.components.Popover.defaults autocompletes to the four axes above.

Reactivity: useComponentDefaults('Popover') subscribes to the theme store — patchTheme re-renders every mounted instance inheriting the changed axis.

API

Props

Slots & slotProps

<Popover> is a compound with 2 named slots. Each accepts a { className?: string } override via slotProps:

<Popover
  showArrow
  content={<Panel />}
  slotProps={{
    content: { className: 'w-72 shadow-2xl' },
    arrow:   { className: 'fill-neutral-900' },
  }}
>
  <Button>Open</Button>
</Popover>

Notes

• Portal-mounted: the floating panel renders into document.body. Parent overflow: hidden and transform won't clip it.
• Focus behavior: on open, focus moves to the first focusable element inside content. On close, focus returns to the trigger. Tab is trapped inside while open (matches dialog semantics).
• Not role="dialog": Radix marks the panel with role="dialog" semantically because it's an interactive floating region. Screen readers announce it as a nested dialog when opened, which is the right behavior for "click a trigger, work inside a small surface, then close".
• When to switch to <Dialog>: if the panel gets big enough that centering it on the viewport is more natural than attaching it to a specific trigger, that's a modal — use <Dialog> instead.
• When to switch to <Menu>: if the panel is a list of commands (label + optional icon + optional shortcut, arrow-key nav), <Menu> gives you the full WAI-ARIA menu pattern for free. Popovers are for freeform content, not command lists.