Skip to main content

Popover

Show anchored interactive content from click or hover.

Props
Slots

Anatomy#

Popover [component; no DOM]
├── Popover.Trigger [part; slot=trigger]
├── Popover.Close [part]
└── positioner [internal]
    └── Popover.Content [part; slot=content]
        └── body [slot]

Content is portaled inside an internal positioning wrapper.

Usage#

Use Popover for anchored interactive content that does not need a labeled modal surface. Use Tooltip for a brief, non-interactive hint. Use DropdownMenu for a compact action list from a visible trigger. Use Dialog or Sheet when the task should take over the page. Use BaseDialog to compose backdrop and content yourself.

import { Button, Popover } from 'moraine'

export function Example() {
  return (
    <Popover>
      <Popover.Trigger as={Button}>Details</Popover.Trigger>
      <Popover.Content>More information</Popover.Content>
    </Popover>
  )
}

Trigger modes and state#

Click toggles the popover by default. openOnHover opens it when a mouse pointer enters the trigger or the trigger receives keyboard focus, and closes it closeDelay ms after the pointer or focus leaves the trigger and content (openDelay and closeDelay default to 100). With openOnHover, clicking the trigger only opens the popover, touch hover is ignored, outside focus no longer dismisses the content, and focus is not restored to the trigger on close unless finalFocus is set. Use controlled open state when the application coordinates visibility.

<Popover>
  <Popover.Trigger as={Button}>Filter</Popover.Trigger>
  <Popover.Content>Click stays open while you choose filters.</Popover.Content>
</Popover>
<Popover openOnHover openDelay={150} closeDelay={100}>
  <Popover.Trigger as={Button}>Profile</Popover.Trigger>
  <Popover.Content>Hover or focus to preview.</Popover.Content>
</Popover>

Placement#

placement chooses the side of the trigger (top, right, bottom, or left; default bottom), and align lines the content up with the trigger edge (start, center, or end; default center). gutter sets the gap to the trigger in pixels, and overflowPadding the minimum distance from the viewport edge (both default to 4). By default, the content moves to another side when placement does not fit (flip; false keeps the side fixed) and slides along the trigger edge to stay in the viewport (slide). Read the rendered side from data-side on the content.

<Popover placement="right" align="start" gutter={8}>
  <Popover.Trigger as={Button}>Details</Popover.Trigger>
  <Popover.Content>Opens to the right of the trigger.</Popover.Content>
</Popover>

Dismissal and accessibility#

Escape and outside interaction close a popover. Closing restores focus to the trigger, except after an outside press or focus move, where focus has already gone elsewhere. Give Popover.Content an accessible name with aria-label when it has no visible label.

modal defaults to false. With modal={true} and a composed Popover.Close, focus stays inside the content, outside content is hidden from assistive technology, and body scroll is locked. Without a Close, the popover stays non-modal so users retain a dismissal route, and development builds log a warning.

modal={false} does not disable Escape or outside dismissal; closeOnEscape and closeOnOutsideClick control them independently. preventScroll can lock body scroll independently of modal.

<Popover>
  <Popover.Trigger as={Button}>Filter</Popover.Trigger>
  <Popover.Content aria-label="Filter settings">Press Escape or click outside.</Popover.Content>
</Popover>
<Popover closeOnEscape={false} closeOnOutsideClick={false} onClosePrevented={onBlocked}>
  <Popover.Trigger as={Button}>Keep open</Popover.Trigger>
  <Popover.Content>Outside click and Escape are blocked.</Popover.Content>
</Popover>

Keyboard interaction#

Keyboard behavior depends on the trigger element and whether the popover is modal. Escape requests dismissal when closeOnEscape allows it; focusable controls inside non-modal content participate in normal document focus order. Modal content contains focus. With openOnHover, Tab from the last control in the content moves to the next focusable element after the trigger, and Shift+Tab from the first control returns to the trigger.

Examples#

Filter deployments or preview a profile#

Click keeps a filter panel open during selection. openOnHover opens an author preview after a delay.

import { Avatar, Badge, Button, Popover } from 'moraine'

export function TriggerModes() {
  return (
    <div class="flex flex-wrap gap-4 items-center">
      <Popover>
        <Popover.Trigger as={Button} variant="outline" leading="i-lucide:sliders-horizontal">
          Click to Filter
        </Popover.Trigger>
        <Popover.Content>
          <div class="p-3 w-64 space-y-2">
            <h4 class="text-xs text-foreground font-semibold">Filter Deployments</h4>
            <p class="text-xs text-muted-foreground">
              Click-triggered popover remains open during interactive selections.
            </p>
            <div class="pt-1 flex gap-1.5">
              <Badge variant="outline" size="sm">
                Production
              </Badge>
              <Badge variant="outline" size="sm">
                Staging
              </Badge>
              <Badge variant="outline" size="sm">
                Canary
              </Badge>
            </div>
          </div>
        </Popover.Content>
      </Popover>

      <Popover openOnHover openDelay={150} closeDelay={100}>
        <Popover.Trigger as={Button} variant="ghost" leading="i-lucide:user">
          Hover for Profile
        </Popover.Trigger>
        <Popover.Content>
          <div class="p-3 w-56 space-y-2">
            <div class="flex gap-2 items-center">
              <Avatar text="AR" size="sm" />
              <div>
                <p class="text-xs text-foreground font-semibold">Alex Rivera</p>
                <p class="text-[0.7rem] text-muted-foreground">Core Maintainer</p>
              </div>
            </div>
            <p class="text-xs text-muted-foreground">
              Hover-triggered info preview with automatic delay timers.
            </p>
          </div>
        </Popover.Content>
      </Popover>
    </div>
  )
}

Label filter settings for dismissal#

Give content an accessible name when it has no visible title. Escape or an outside click closes the popover.

import { Button, Popover } from 'moraine'

export function DismissalUsage() {
  return (
    <Popover>
      <Popover.Trigger as={Button} variant="outline" leading="i-lucide:sliders-horizontal">
        Filter
      </Popover.Trigger>
      <Popover.Content aria-label="Filter settings">
        <div class="text-xs p-3 w-48 space-y-2">
          <p class="text-foreground font-medium">Filter Settings</p>
          <p class="text-muted-foreground">Press Escape or click outside to dismiss.</p>
        </div>
      </Popover.Content>
    </Popover>
  )
}

Preview an author card on hover#

Hover or focus the trigger to follow an author. Open and close delays keep the card from flashing.

import { Avatar, Badge, Button, Popover } from 'moraine'

export function HoverMode() {
  return (
    <div class="flex flex-wrap gap-3 items-center">
      <Popover openOnHover openDelay={180} closeDelay={120}>
        <Popover.Trigger as={Button} variant="outline" leading="i-lucide:user">
          Hover for Author Card
        </Popover.Trigger>
        <Popover.Content>
          <div class="p-4 rounded-xl bg-card max-w-xs space-y-3">
            <div class="flex items-start justify-between">
              <Avatar text="AM" alt="Alex Morgan" size="lg" />
              <Button size="xs">Follow</Button>
            </div>

            <div>
              <div class="flex gap-1.5 items-center">
                <h4 class="text-sm font-semibold">Alex Morgan</h4>
                <Badge variant="outline" size="sm">
                  Author
                </Badge>
              </div>
              <p class="text-xs text-muted-foreground font-mono">@alex.morgan</p>
            </div>

            <p class="text-xs text-foreground">
              Building accessible, high-performance UI primitives for SolidJS and web standards.
            </p>

            <div class="text-xs text-muted-foreground pt-1 border-t border-border flex gap-3">
              <span>
                <strong class="text-foreground font-semibold">1.4k</strong> followers
              </span>
              <span>
                <strong class="text-foreground font-semibold">328</strong> following
              </span>
            </div>
          </div>
        </Popover.Content>
      </Popover>
    </div>
  )
}

Keep a popover open until an explicit close#

closeOnEscape={false} and closeOnOutsideClick={false} block Escape and outside clicks. onClosePrevented counts blocked attempts.

import { Button, Popover } from 'moraine'
import { createSignal } from 'solid-js'

export function DismissControl() {
  const [preventedCloseCount, setPreventedCloseCount] = createSignal(0)

  return (
    <div class="flex flex-wrap gap-3 items-center">
      <Popover
        defaultOpen
        closeOnEscape={false}
        closeOnOutsideClick={false}
        onClosePrevented={() => setPreventedCloseCount((value) => value + 1)}
      >
        <Popover.Trigger as={Button} variant="soft" tone="neutral">
          Try close me
        </Popover.Trigger>
        <Popover.Content>
          <div class="p-3 space-y-1">
            <p class="text-sm font-medium">Persistent popover</p>
            <p class="text-xs text-muted-foreground">
              Prevented close attempts: {preventedCloseCount()}
            </p>
          </div>
        </Popover.Content>
      </Popover>
    </div>
  )
}

API Reference#

Attributes#

Attributes
data-closed
Slot: popover-triggerpopover-content
Description: Present when disclosure or transition content is closed.
data-disabled
Slot: popover-trigger
Description: Present when the component, slot, or item is disabled.
data-expanded
Slot: popover-triggerpopover-content
Description: Present when the panel, accordion, or menu is expanded.
data-align
Slot: popover-content
Description: Stores the resolved alignment of positioned content.
data-side
Slot: popover-content
Description: Stores the resolved floating or drawer content side.

Props#

Popover#

Prop

Trigger#

Renders a <button> element by default.

Prop

Content#

Props for the Popover component. Renders a <div> element by default.

Prop

Close#

Renders a <button> element by default.

Prop