.'
children:
- name: Popover.Arrow
description: 'Renders a
pointing at the anchor.'
- name: Popover.Title
description: 'Renders an
that names the dialog.'
- name: Popover.Description
description: 'Renders a that describes it.'
- name: Popover.Close
description: 'Renders a that closes the popup.'
---
::
```vue
Share
Share this page
Anyone with the link can read it.
Done
```
## Examples
### Opening on hover
Set `options.openOnHover` and the trigger opens the popover after `delay` and
closes it after `closeDelay`. The gap between the trigger and the popup is
crossed with the pointer, so entering either one cancels the other’s timer.
```vue
```
A popover opened by hover leaves focus where the pointer left it. One opened by
a click moves focus into the popup.
### Modal
`options.modal` traps focus in the popup and marks the rest of the document
`inert`, so nothing behind it can be reached until it closes. Pair it with
`options.backdrop` to lay a surface over the page while it is open.
```vue
Share
…
```
The backdrop has no dismiss behaviour of its own: the popup’s layer already
closes on a pointer down outside.
### Where focus goes
`initialFocus` and `finalFocus` take an element, or a function that receives
the reason the popover opened or closed and returns one. `false` leaves focus
alone.
```vue
```
Without either, focus moves to the first tabbable element in the popup, or to
the popup itself, and returns to the trigger on close.
### Positioning
`Popover.Content` positions itself against the trigger, steered by the
`floating` keys on the root’s `options`; the options table below lists every
one of them. The resolved placement comes back
as `data-side` and `data-align`; read those rather than the props you passed,
since flipping can change either one.
```vue
```
Pass `anchor` to position against something else, and pass any of the ten
floating keys straight to the content to override the options for one instance.
```vue
```
The content writes `--rack-floating-anchor-width`,
`--rack-floating-anchor-height`, `--rack-floating-available-width`,
`--rack-floating-available-height` and `--rack-floating-transform-origin` onto
the floating box, which is how a popup matches the width of its trigger or
stops short of the edge of the screen.
```css
.popup {
min-width: var(--rack-floating-anchor-width);
max-height: var(--mirror-popover-popup-max-height);
}
```
### Where the popup renders
The content teleports to the end of ``, which is what keeps a popup out
of an ancestor’s `overflow: hidden` and above the rest of the page. Turn it off
to render in place, or name a target of your own.
```vue
```
`options.backdrop` adds a fixed `` behind the popup.
```vue
```
### Animating it
The popup and the backdrop each take a Vue transition name, and the timing
lives in your CSS under that name. Popover ships without one, so a popup
unmounts as it closes until you name it.
```vue
```
```css
.app-popup-enter-active,
.app-popup-leave-active {
transition:
opacity 150ms,
transform 150ms;
}
.app-popup-enter-from,
.app-popup-leave-to {
opacity: 0;
transform: scale(0.96);
}
```
The popup stays mounted until the leave has finished. For a keyframe animation
rather than a transition, read `data-state` instead, which is `open` or
`closed` for as long as the popup is rendered, and set `options.forceMount` to
keep the popup in the DOM whatever it is doing.
[Animation](/components/animation) has both patterns in full.
### Reaching the popover from anywhere
Give the root an `id` and `useMirrorPopover(id)` opens, closes and reads that
popover from anywhere in the app.
```vue
Share
```
### Styling from state
Every part writes its state to `data-*`, so style it with attribute selectors.
```css
.trigger[data-popup-open='true'] {
background: var(--app-color-primary-bg-solid-active);
}
.popup[data-side='top'] {
transform-origin: bottom center;
}
.arrow[data-uncentered='true'] {
opacity: 0;
}
```
The content’s three boxes are not parts, so they are reached by their
`data-scope` or by the class each one ships. A `class` on `Popover.Content` is
applied to the popup, the box you paint.
```vue
```
```css
.mirror-popover-floating {
--mirror-popover-floating-z-index: 80;
}
[data-scope='backdrop'] {
background: rgb(0 0 0 / 0.4);
}
```
## API reference
**Module.** A bundled `options` object on the root, and `useMirrorPopover(id)`
as the programmatic API. Every part takes `id` to resolve a popover it is not
nested inside.
### `Popover.Root`
Renders its children. It is a provider.
#### Props
::docs-table
---
columns:
- label: Prop
- label: Type
- label: Default
rows:
- items:
- label: id
description: '[The instance ID](#reaching-the-popover-from-anywhere).'
- label: string
- label: generated
plaintext: true
- items:
- label: open
description: Open state. `v-model:open`.
- label: 'boolean | undefined'
- label: undefined
- items:
- label: defaultOpen
description: 'Initial open state when [uncontrolled](/components/composition#controlled-and-uncontrolled).'
- label: boolean
- label: 'false'
- items:
- label: options
description: Everything else. Deep-merged over the defaults.
- label: PopoverOptions
- label: see below
plaintext: true
---
::
#### Options
::docs-table
---
columns:
- label: Option
- label: Type
- label: Default
rows:
- items:
- label: modal
description: 'Makes the popover [modal](#modal).'
- label: boolean
- label: 'false'
- items:
- label: openOnHover
description: 'The pointer [opens the popover](#opening-on-hover) as well as the press.'
- label: boolean
- label: 'false'
- items:
- label: delay
description: Milliseconds the pointer has to rest before it opens.
- label: number
- label: '300'
- items:
- label: closeDelay
description: Milliseconds before it closes again once the pointer leaves.
- label: number
- label: '0'
- items:
- label: disabled
description: Disables the trigger and refuses opening.
- label: boolean
- label: 'false'
- items:
- label: forceMount
description: Keeps the popup and the backdrop mounted while closed.
- label: boolean
- label: 'false'
- items:
- label: backdrop
description: 'Renders a fixed `
` behind the popup.'
- label: boolean
- label: 'false'
- items:
- label: dismiss.escape
description: Escape closes the popup.
- label: boolean
- label: 'true'
- items:
- label: dismiss.pointerDownOutside
description: A pointer down outside closes the popup.
- label: boolean
- label: 'true'
- items:
- label: dismiss.focusOutside
description: Focus leaving closes the popup.
- label: boolean
- label: 'true'
- items:
- label: focus.trapped
description: Focus is trapped in the popup. `modal` implies it.
- label: boolean
- label: 'false'
- items:
- label: focus.restore
description: Closing returns focus to the trigger.
- label: boolean
- label: 'true'
- items:
- label: focus.initial
description: 'Where [focus goes](#where-focus-goes) on open.'
- label: 'boolean | HTMLElement | ((reason) => …)'
- label: 'null'
- items:
- label: focus.final
description: 'Where [focus goes](#where-focus-goes) on close.'
- label: 'boolean | HTMLElement | ((reason) => …)'
- label: 'null'
- items:
- label: portal.to
description: The teleport target for the content.
- label: 'string | HTMLElement'
- label: body
plaintext: true
- items:
- label: portal.disabled
description: Renders the content in place instead.
- label: boolean
- label: 'false'
- items:
- label: portal.defer
description: 'Resolves the target after mount, for a target rendered by the same app.'
- label: boolean
- label: 'false'
- items:
- label: floating.side
description: Preferred side. Reactive.
- label: '''top'' | ''right'' | ''bottom'' | ''left'''
- label: '''bottom'''
- items:
- label: floating.sideOffset
description: Gap from the anchor, in pixels.
- label: number
- label: '8'
- items:
- label: floating.align
description: Alignment along that side. Reactive.
- label: '''start'' | ''center'' | ''end'''
- label: '''center'''
- items:
- label: floating.alignOffset
description: Shift along the alignment axis, in pixels.
- label: number
- label: '0'
- items:
- label: floating.strategy
description: Positioning strategy.
- label: '''absolute'' | ''fixed'''
- label: '''absolute'''
- items:
- label: floating.flip
description: Flip to the opposite side when there is no room.
- label: boolean
- label: 'true'
- items:
- label: floating.shift
description: Slide along the side to stay in view.
- label: boolean
- label: 'true'
- items:
- label: floating.sticky
description: Keep the popup in view once the anchor has scrolled past.
- label: boolean
- label: 'false'
- items:
- label: floating.collisionPadding
description: Padding used by flipping and shifting.
- label: number
- label: '8'
- items:
- label: floating.arrowPadding
description: How close the arrow may come to the corners of the popup.
- label: number
- label: '5'
- items:
- label: transition.popup
description: Vue transition name for the popup.
- label: string
- label: undefined
- items:
- label: transition.backdrop
description: Vue transition name for the backdrop.
- label: string
- label: undefined
---
::
#### Emits
::docs-table
---
columns:
- label: Emit
- label: Payload
rows:
- items:
- label: update:open
description: The popup opens or closes.
- label: boolean
- items:
- label: openChange
description: The same change, with the reason it happened.
- label: 'boolean, PopoverChangeReason'
---
::
`PopoverChangeReason` is one of `trigger-press`, `trigger-hover`,
`outside-press`, `escape-key`, `close-press`, `focus-out` or `imperative`.
### `Popover.Trigger`
Renders a `
` with `aria-haspopup="dialog"`.
#### Props
::docs-table
---
columns:
- label: Prop
- label: Type
- label: Default
rows:
- items:
- label: disabled
description: Escape hatch over the options.
- label: boolean
- label: options.disabled
---
::
#### Slot props
::docs-table
---
columns:
- label: Prop
- label: Type
rows:
- items:
- label: open
description: Mirrors `data-popup-open`.
- label: boolean
- items:
- label: disabled
description: Mirrors `data-disabled`.
- label: boolean
- items:
- label: side
description: Mirrors `data-side`.
- label: 'PopoverSide | undefined'
- items:
- label: align
description: Mirrors `data-align`.
- label: 'PopoverAlign | undefined'
---
::
### `Popover.Content`
Renders everything that floats: the teleport, the floating box and the popup.
Everything in its default slot renders inside the popup. It anchors on
`Popover.Trigger`.
#### Layers
None of the three is a part, so each is styled through its `data-scope` or the
class it ships. A `class` on the content itself is applied to the popup.
::docs-table
---
columns:
- label: Layer
- label: Element
- label: Publishes
rows:
- items:
- label: portal
description: The teleport. Configured through `options.portal`.
- label: none
plaintext: true
- label: nothing
plaintext: true
- items:
- label: backdrop
description: '`.mirror-popover-backdrop`, only under `options.backdrop`.'
- label: 'div[role=presentation]'
- label: '`data-popover`, `data-state`'
plaintext: true
- items:
- label: floating
description: '`.mirror-popover-floating`. Carries the floating styles and the `--rack-floating-*` set.'
- label: div
- label: '`data-side`, `data-align`, `data-anchor-hidden`, `data-state`'
plaintext: true
- items:
- label: popup
description: '`.mirror-popover-popup`. Presence, dismissal, focus and the modal behaviour live here.'
- label: 'div[role=dialog]'
- label: '`data-popover`, `data-side`, `data-align`, `data-state`'
plaintext: true
---
::
#### Props
Every prop below but `forceMount`, `anchor`, `initialFocus` and `finalFocus` is
an escape hatch over the matching `options.floating` key, and only `side` and
`align` stay reactive after mount.
::docs-table
---
columns:
- label: Prop
- label: Type
- label: Default
rows:
- items:
- label: forceMount
description: Keeps the popup and the backdrop mounted while closed.
- label: boolean
- label: options.forceMount
- items:
- label: anchor
description: 'Position against this element [instead of the trigger](#positioning).'
- label: 'HTMLElement | (() => HTMLElement | null)'
- label: the trigger
plaintext: true
- items:
- label: initialFocus
description: 'Where [focus goes](#where-focus-goes) on open.'
- label: 'boolean | HTMLElement | ((reason) => …)'
- label: options.focus.initial
- items:
- label: finalFocus
description: 'Where [focus goes](#where-focus-goes) on close.'
- label: 'boolean | HTMLElement | ((reason) => …)'
- label: options.focus.final
- items:
- label: side
description: Preferred side.
- label: '''top'' | ''right'' | ''bottom'' | ''left'''
- label: '''bottom'''
- items:
- label: sideOffset
description: Gap from the anchor, in pixels.
- label: number
- label: '8'
- items:
- label: align
description: Alignment along that side.
- label: '''start'' | ''center'' | ''end'''
- label: '''center'''
- items:
- label: alignOffset
description: Shift along the alignment axis, in pixels.
- label: number
- label: '0'
- items:
- label: strategy
description: Positioning strategy.
- label: '''absolute'' | ''fixed'''
- label: '''absolute'''
- items:
- label: flip
description: Flip to the opposite side when there is no room.
- label: boolean
- label: 'true'
- items:
- label: shift
description: Slide along the side to stay in view.
- label: boolean
- label: 'true'
- items:
- label: sticky
description: Keep the popup in view once the anchor has scrolled past.
- label: boolean
- label: 'false'
- items:
- label: collisionPadding
description: Padding used by flipping and shifting.
- label: number
- label: '8'
- items:
- label: arrowPadding
description: How close the arrow may come to the corners of the popup.
- label: number
- label: '5'
---
::
#### Slot props
::docs-table
---
columns:
- label: Prop
- label: Type
rows:
- items:
- label: open
description: Mirrors `data-state`.
- label: boolean
- items:
- label: side
description: Resolved after collision handling.
- label: PopoverSide
- items:
- label: align
description: Resolved after collision handling.
- label: PopoverAlign
- items:
- label: anchorHidden
description: Mirrors `data-anchor-hidden`.
- label: boolean
---
::
### `Popover.Arrow`
Renders a `` pointing at the anchor. It ships
`position: absolute` and takes its offset from the same positioning pass as the
popup; the side it points away from is yours to style. It must be nested inside
a `Popover.Content`.
#### Slot props
::docs-table
---
columns:
- label: Prop
- label: Type
rows:
- items:
- label: side
description: Mirrors `data-side`.
- label: PopoverSide
- items:
- label: align
description: Mirrors `data-align`.
- label: PopoverAlign
- items:
- label: uncentered
description: Mirrors `data-uncentered`.
- label: boolean
---
::
### `Popover.Title`
Renders an `
` and names the dialog through `aria-labelledby`.
### `Popover.Description`
Renders a ` ` and describes it through `aria-describedby`.
### `Popover.Close`
Renders a `` that closes the popup.
#### Props
::docs-table
---
columns:
- label: Prop
- label: Type
- label: Default
rows:
- items:
- label: disabled
description: Escape hatch over the options.
- label: boolean
- label: options.disabled
---
::
### Composable
`useMirrorPopover(id)` reaches a popover from anywhere in the app.
::docs-table
---
columns:
- label: Key
- label: Type
rows:
- items:
- label: isOpen
description: '`true` while the popup is open.'
- label: ComputedRef
escape: true
- items:
- label: open
description: Opens the popup.
- label: '(reason?: PopoverChangeReason) => void'
escape: true
- items:
- label: close
description: Closes the popup.
- label: '(reason?: PopoverChangeReason) => void'
escape: true
- items:
- label: toggle
description: Opens or closes.
- label: '(reason?: PopoverChangeReason) => void'
escape: true
- items:
- label: side
description: The side the popup ended up on.
- label: 'ComputedRef'
escape: true
- items:
- label: align
description: The alignment it ended up with.
- label: 'ComputedRef'
escape: true
---
::
### Data attributes
::data-attributes
::
### CSS variables
::css-variables
::
### Errors
::docs-table
---
columns:
- label: Code
rows:
- items:
- label: missing_popover_context
description: A `Popover` part rendered outside `Popover.Root` and received no `id`.
- items:
- label: missing_popover_content
description: A `Popover.Arrow` rendered outside a `Popover.Content`.
---
::
## Accessibility
The trigger is a `` with `aria-haspopup="dialog"`, `aria-expanded` and
`aria-controls`. The popup is a `role="dialog"` named by its title and described
by its description, and it gains `aria-modal` only while `options.modal` is set.
::docs-table
---
columns:
- label: Key
- label: Behaviour
rows:
- items:
- label: '`Enter` / `Space` on the trigger'
plaintext: true
- label: Toggles the popup. On a non-native trigger, Space acts on `keyup`.
plaintext: true
- items:
- label: Tab
- label: Moves through the popup. While `modal` or `focus.trapped` is set, it stays inside.
plaintext: true
- items:
- label: Escape
- label: Closes the popup and returns focus to the trigger. Nested popovers close from the inside out.
plaintext: true
---
::
Focus moves into the popup when it opens by press, and stays where it is when it
opens by hover.