---
title: Popover
description: Show anchored interactive content from click or hover.
package: moraine
version: 0.11.0
repository: https://github.com/subframe7536/moraine
---

# Popover

> Show anchored interactive content from click or hover.

## Anatomy

```text
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](https://moraine.subf.dev/components/tooltip.md) for a brief, non-interactive hint. Use
[DropdownMenu](https://moraine.subf.dev/components/dropdown-menu.md) for a compact action list from a visible trigger. Use
[Dialog](https://moraine.subf.dev/components/dialog.md) or [Sheet](https://moraine.subf.dev/components/sheet.md) when the task should take over the
page. Use [BaseDialog](https://moraine.subf.dev/components/base-dialog.md) to compose backdrop and content yourself.

```tsx
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.

```tsx
<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.

```tsx
<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`.

```tsx
<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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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 | Slot | Description |
| --- | --- | --- |
| `data-closed` | `popover-trigger`, `popover-content` | Present when disclosure or transition content is closed. |
| `data-disabled` | `popover-trigger` | Present when the component, slot, or item is disabled. |
| `data-expanded` | `popover-trigger`, `popover-content` | Present when the panel, accordion, or menu is expanded. |
| `data-align` | `popover-content` | Stores the resolved alignment of positioned content. |
| `data-side` | `popover-content` | Stores the resolved floating or drawer content side. |

### Props

#### Popover

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| align | 'start' \| 'center' \| 'end' \| undefined | 'center' | Alignment of the content along the trigger edge: `'start'` and `'end'` line up the content<br>edge with the matching trigger edge, `'center'` centers it. Combines with `placement`. |
| closeDelay | number \| undefined | 100 | Delay in milliseconds between the pointer or focus leaving the trigger and content and<br>closing; re-entering within the delay keeps it open. Only used with `openOnHover`. |
| closeOnEscape | boolean \| undefined | true | Whether pressing Escape closes the content. When `false` the key press is blocked, the content<br>stays open and `onClosePrevented` is called. |
| closeOnOutsideClick | boolean \| undefined | true | Whether a pointer press outside the content and its trigger, or focus moving outside, closes<br>the content (focus does not dismiss hover-opened popovers). When `false` the attempt is blocked,<br>the content stays open and `onClosePrevented` is called. |
| defaultOpen | boolean \| undefined | false | Initial open state when uncontrolled. Ignored while `open` is set. |
| disabled | boolean \| undefined | false | Whether trigger interactions and content rendering are disabled. |
| finalFocus | HTMLElement \| (() => HTMLElement \| undefined) \| false \| undefined | — | Element (or accessor resolving to one) that receives focus after the content closes, or<br>`false` to skip the close-time focus restore. Defaults to the trigger. An accessor that<br>returns `undefined` restores no focus. Focus is not restored when a non-modal content is<br>dismissed by an outside press or focus move, since focus already went elsewhere. Hover-opened<br>popovers (`openOnHover`) default to not restoring focus. |
| flip | boolean \| string \| undefined | true | Whether the content moves to another side when the preferred `placement` does not fit in the<br>viewport. `false` keeps the side fixed. A string is a space-delimited list of fallback<br>placements tried in order, each `top`, `right`, `bottom` or `left`, optionally suffixed with<br>`-start` or `-end`; any other entry throws an error. |
| forceMount | boolean \| undefined | false | Whether the content stays in the DOM while closed, hidden and marked with `data-closed`, for<br>example to measure it or keep its state. Has no effect while `disabled`. |
| gutter | number \| undefined | 4 | Gap in pixels between the trigger and the content. |
| id | string \| undefined | — | Unique identifier used to derive the content id, which becomes `<id>-content`. Generated when<br>omitted. |
| modal | boolean \| undefined | false | Whether the content traps focus, hides outside content from assistive technology, prevents<br>the native default action of outside pointer events, and locks body scroll.<br>This is enabled only when Popover.Content composes Popover.Close; otherwise the Popover<br>remains non-modal so assistive-technology users retain a dismissal route, and a DEV<br>warning is logged. Outside and Escape dismissal remain controlled by `closeOnOutsideClick`<br>and `closeOnEscape`. |
| onClosePrevented | (() => void) \| undefined | — | Called with no arguments when Escape (`closeOnEscape` is `false`) or an outside press or focus<br>move (`closeOnOutsideClick` is `false`) tried to close the content and was blocked. |
| onOpenChange | ((open: boolean) => void) \| undefined | — | Called with the next open state when an interaction (trigger press, hover or focus delay,<br>Escape, outside press) requests a change. It is not called when `open` is changed from outside,<br>and it does not apply the change itself when `open` is controlled: update `open` in the handler. |
| open | boolean \| undefined | — | Controlled open state. Pair it with `onOpenChange`; leave it `undefined` to let the component<br>manage its own state (see `defaultOpen`). `disabled` forces the content closed regardless. |
| openDelay | number \| undefined | 100 | Delay in milliseconds between pointer enter or trigger focus and opening. Only used with<br>`openOnHover`. |
| openOnHover | boolean \| undefined | false | Opens the popover when a mouse pointer enters the trigger or the trigger receives keyboard<br>focus, and closes it `closeDelay` ms after the pointer or focus leaves the trigger and content.<br>Clicking the trigger then only opens it instead of toggling. Touch hover is ignored. Outside<br>focus no longer dismisses the content, and focus is not restored to the trigger on close<br>unless `finalFocus` is set. |
| overflowPadding | number \| undefined | 4 | Minimum padding in pixels between the content and the viewport edge. |
| placement | 'top' \| 'right' \| 'bottom' \| 'left' \| undefined | 'bottom' | Side of the trigger the content opens on. The rendered side can differ when `flip` moves it to<br>fit the viewport; read it from `data-side` on the content. |
| preventScroll | boolean \| undefined | false | Whether body scroll is locked while the content is present. A modal content always locks it. |
| shift | number \| undefined | 0 | Offset in pixels along the trigger edge (horizontal for `top` and `bottom` placements,<br>vertical for `left` and `right`), added to the position given by `align`. |
| slide | boolean \| undefined | true | Whether the content slides along the trigger edge (horizontally for `top` and `bottom`<br>placements, vertically for `left` and `right`) to stay inside the viewport, keeping<br>`overflowPadding` from the edge, instead of overflowing. |
| children | JSX.Element \| undefined | — | Composed trigger and content primitives. |
| classes | Classes \| undefined | — | Family slot class defaults for this instance. |
| styles | Styles \| undefined | — | Family slot style defaults for this instance. |

**`finalFocus` example**

```tsx
import { Button, Popover } from 'moraine'

<Popover finalFocus={() => document.getElementById('search') ?? undefined}>
  <Popover.Trigger as={Button}>Filters</Popover.Trigger>
  <Popover.Content>Filter options</Popover.Content>
</Popover>
```

**`flip` example**

```tsx
import { Button, Popover } from 'moraine'

<Popover placement="bottom" flip="top bottom-end">
  <Popover.Trigger as={Button}>Details</Popover.Trigger>
  <Popover.Content>More information</Popover.Content>
</Popover>
```

**`onOpenChange` example**

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

const [open, setOpen] = createSignal(false)

<Popover open={open()} onOpenChange={setOpen}>
  <Popover.Trigger as={Button}>Details</Popover.Trigger>
  <Popover.Content>More information</Popover.Content>
</Popover>
```

#### Popover.Trigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| disabled | boolean \| undefined | — | Whether this trigger is disabled. |
| as | T \| undefined | 'button' | Element or component to render as. |
| children | JSX.Element \| undefined | — | Trigger label and visual content. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |

#### Popover.Content

Props for the Popover component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children | JSX.Element \| undefined | — | Body content. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |

#### Popover.Close

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| disabled | boolean \| undefined | — | Whether this trigger is disabled. |
| as | T \| undefined | 'button' | Element or component to render as. |
| children | JSX.Element \| undefined | — | Trigger label and visual content. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |
