Popover
updatedRich content in a floating panel anchored to a trigger.
Installation
Usage
<script setup lang="ts">
import { Button } from '@/components/ui/button'
import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
</script>
<template>
<Popover>
<PopoverTrigger as-child>
<Button variant="outline" color="neutral">Open</Button>
</PopoverTrigger>
<PopoverContent>Place content for the popover here.</PopoverContent>
</Popover>
</template>
Put anything inside. It opens below the trigger and moves to stay on screen. Escape or a click outside closes it.
Want it anchored to something else, like the input your button sits in? Wrap that element in PopoverAnchor.
Examples
Modal
By default, the page stays clickable: a click outside closes the popover and also hits whatever is under it.
Add modal, and the page locks while it's open: focus stays inside, scrolling stops, and a click outside only closes the popover.
API Reference
PopoverContent accepts class, merged over its base classes.
Popover
| Prop | Default | Type and description |
|---|---|---|
| defaultOpen | — | booleanWhether it starts open when |
| open | — | booleanWhether it is open, bound with |
| modal | — | booleanShuts the page while open: outside clicks only close it, the page does not scroll and screen readers see only the panel. A scrim takes the first outside click so nothing under it is activated. |
| Event | Payload and description |
|---|---|
| update:open | [value: boolean]Fires when it opens or closes. |
| Slot | Scope and description |
|---|---|
| default | { open: boolean; close: () => void; }The trigger, an optional anchor and the content. Receives |
PopoverContent
| Prop | Default | Type and description |
|---|---|---|
| forceMount | — | booleanKeeps the panel mounted while closed, for animating it with a JavaScript library. |
| memoDependencies | — | unknown[]Values that should re-run the position update when they change. |
| side | — | "top" | "right" | "bottom" | "left"The side of the trigger to open on. Flips to the other side when there is no room, unless |
| sideOffset | 4 | numberDistance in pixels from the trigger. |
| sideFlip | — | booleanFlips to the opposite side when the preferred one would overflow. |
| align | "center" | "center" | "start" | "end"Alignment against the trigger along the chosen side. |
| alignOffset | — | numberOffset in pixels from the |
| alignFlip | — | booleanFlips the alignment when it would overflow. |
| avoidCollisions | — | booleanKeeps the panel inside the collision boundary by flipping and shifting it. |
| collisionBoundary | — | Element | (Element | null)[] | nullThe element or elements used as the collision boundary. The viewport by default. |
| collisionPadding | — | number | Partial<Record<"top" | "right" | "bottom" | "left", number>>Distance in pixels from the boundary edges where collisions start. |
| arrowPadding | — | numberPadding between an arrow and the panel's corners. |
| hideShiftedArrow | — | booleanHides an arrow when the panel is shifted so far that the arrow would not point at the trigger. |
| sticky | — | "partial" | "always"
|
| hideWhenDetached | — | booleanHides the panel when the trigger is scrolled out of view. |
| positionStrategy | — | "absolute" | "fixed"The CSS position used to place the panel. |
| updatePositionStrategy | — | "always" | "optimized"
|
| disableUpdateOnLayoutShift | — | booleanStops recomputing the position when the layout shifts. |
| prioritizePosition | — | booleanKeeps the preferred side and alignment and lets the panel overflow instead of flipping. |
| reference | — | ReferenceElementA virtual element to position against instead of the trigger. |
| dir | — | DirectionReading direction. Mirrors the layout and arrow keys in |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| disableOutsidePointerEvents | — | booleanShuts the page to the pointer while open, as |
| Event | Payload and description |
|---|---|
| escapeKeyDown | [event: KeyboardEvent]Fires on Escape. Call |
| pointerDownOutside | [event: PointerDownOutsideEvent]Fires on a pointer press outside. Call |
| focusOutside | [event: FocusOutsideEvent]Fires when focus moves outside. Call |
| interactOutside | [event: PointerDownOutsideEvent | FocusOutsideEvent]Fires on any press or focus outside. Call |
| openAutoFocus | [event: Event]Fires when focus moves into the panel on open. Call |
| closeAutoFocus | [event: Event]Fires when focus returns to the trigger on close. Call |
| Slot | Scope and description |
|---|---|
| default | {}The popover's content. |
PopoverAnchor
| Prop | Default | Type and description |
|---|---|---|
| reference | — | ReferenceElementA virtual element to position the content against. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The element the content is positioned against instead of the trigger. |
PopoverTrigger
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The element that toggles the popover, usually a |
Props
- defaultOpen
booleanWhether it starts open whenv-model:openis not used.- open
booleanWhether it is open, bound withv-model:open.- modal
booleanShuts the page while open: outside clicks only close it, the page does not scroll and screen readers see only the panel. A scrim takes the first outside click so nothing under it is activated.
Emits
- update:open
[value: boolean]Fires when it opens or closes.
Slots
- default
{ open: boolean; close: () => void; }The trigger, an optional anchor and the content. Receivesopenandclose.
Props
- forceMount
booleanKeeps the panel mounted while closed, for animating it with a JavaScript library.- memoDependencies
unknown[]Values that should re-run the position update when they change.- side
"top" | "right" | "bottom" | "left"The side of the trigger to open on. Flips to the other side when there is no room, unlessavoidCollisionsis off.- sideOffset
4 numberDistance in pixels from the trigger.- sideFlip
booleanFlips to the opposite side when the preferred one would overflow.- align
"center" "center" | "start" | "end"Alignment against the trigger along the chosen side.- alignOffset
numberOffset in pixels from thealignposition.- alignFlip
booleanFlips the alignment when it would overflow.- avoidCollisions
booleanKeeps the panel inside the collision boundary by flipping and shifting it.- collisionBoundary
Element | (Element | null)[] | nullThe element or elements used as the collision boundary. The viewport by default.- collisionPadding
number | Partial<Record<"top" | "right" | "bottom" | "left", number>>Distance in pixels from the boundary edges where collisions start.- arrowPadding
numberPadding between an arrow and the panel's corners.- hideShiftedArrow
booleanHides an arrow when the panel is shifted so far that the arrow would not point at the trigger.- sticky
"partial" | "always"partialkeeps the panel attached to the trigger while scrolling;alwaysalso lets it detach from the trigger to stay in the boundary.- hideWhenDetached
booleanHides the panel when the trigger is scrolled out of view.- positionStrategy
"absolute" | "fixed"The CSS position used to place the panel.- updatePositionStrategy
"always" | "optimized"alwaysrecomputes the position on every animation frame instead of only on layout changes.- disableUpdateOnLayoutShift
booleanStops recomputing the position when the layout shifts.- prioritizePosition
booleanKeeps the preferred side and alignment and lets the panel overflow instead of flipping.- reference
ReferenceElementA virtual element to position against instead of the trigger.- dir
DirectionReading direction. Mirrors the layout and arrow keys inrtl.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.- disableOutsidePointerEvents
booleanShuts the page to the pointer while open, asmodalon the root does.
Emits
- escapeKeyDown
[event: KeyboardEvent]Fires on Escape. CallpreventDefault()to keep it open.- pointerDownOutside
[event: PointerDownOutsideEvent]Fires on a pointer press outside. CallpreventDefault()to keep it open.- focusOutside
[event: FocusOutsideEvent]Fires when focus moves outside. CallpreventDefault()to keep it open.- interactOutside
[event: PointerDownOutsideEvent | FocusOutsideEvent]Fires on any press or focus outside. CallpreventDefault()to keep it open.- openAutoFocus
[event: Event]Fires when focus moves into the panel on open. CallpreventDefault()to keep focus where it is.- closeAutoFocus
[event: Event]Fires when focus returns to the trigger on close. CallpreventDefault()to keep focus where it is.
Slots
- default
{}The popover's content.
Props
- reference
ReferenceElementA virtual element to position the content against.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}The element the content is positioned against instead of the trigger.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}The element that toggles the popover, usually aButtonwithas-child.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| popover-content | data-state, data-side, data-align | The panel. |
| popover-scrim | — | The transparent layer under a modal popover that takes the first outside click. |