usePopover
A composable for native popover API behavior with CSS anchor positioning.
Usage
usePopover manages a popover’s open/close state, generates CSS anchor positioning styles, and synchronizes reactive state with native popover toggle events. Spread anchorStyles on the activator, contentAttrs and contentStyles on the content element, and call attach() to wire up the native popover lifecycle.
<script setup lang="ts">
import { usePopover } from '@vuetify/v0'
import { useTemplateRef } from 'vue'
const content = useTemplateRef('content')
const {
isOpen,
toggle,
attach,
anchorStyles,
contentAttrs,
contentStyles,
} = usePopover({ positionArea: 'bottom' })
attach(content)
</script>
<template>
<button :style="anchorStyles" @click="toggle">
{{ isOpen ? 'Close' : 'Open' }}
</button>
<div
ref="content"
v-bind="contentAttrs"
:style="contentStyles"
>
Popover content
</div>
</template>Architecture
usePopover builds on useEventListener for native toggle event synchronization. It is a standalone composable — not part of the compound Popover component — making it ideal for building select, combobox, tooltip, and menu components directly.
Options
| Option | Type | Default | Notes |
|---|---|---|---|
id | string | auto | Base ID for anchor name and popover id. Auto-generated if not provided |
positionArea | string | 'bottom' | CSS position-area value — controls where the content appears relative to the anchor |
positionTry | string | 'most-width bottom' | CSS position-try-fallbacks value — fallback positions when the primary area overflows |
isOpen | Ref<boolean> | — | External ref for bidirectional open state (e.g., from defineModel) |
showDelay | number | 0 | Milliseconds to wait before showing the popover (hover/focus use cases) |
hideDelay | number | 0 | Milliseconds to wait before hiding the popover (prevents premature close on mouse leave) |
Reactivity
| Property/Method | Reactive | Notes |
|---|---|---|
isOpen | ShallowRef, tracks whether the popover is open | |
open() | - | Open the popover |
close() | - | Close the popover |
toggle() | - | Toggle open/close |
attach(el) | - | Wire native show/hide watch + toggle event sync to a content element |
anchorStyles | Readonly Ref, CSS anchor-name for the activator element | |
contentAttrs | Readonly Ref, id and popover attribute for the content element | |
contentStyles | Readonly Ref, CSS anchor positioning styles for the content element |
Examples
CSS Anchor Positioning
A popover positioned relative to its trigger using the native Popover API and CSS anchor positioning, demonstrating anchorStyles, contentAttrs, and contentStyles.
This popover uses the native Popover API with CSS anchor positioning. It flips automatically when near viewport edges.
Functions
usePopover
(options?: PopoverOptions) => PopoverReturnOptions
isOpen
Ref<boolean, boolean> | undefinedExternal ref for bidirectional open state (e.g., from defineModel)
Properties
anchorStyles
Readonly<Ref<Record<string, string>, Record<string, string>>>Styles to spread on the activator element (anchor-name)
contentAttrs
Readonly<Ref<{ id: string; popover: ""; }, { id: string; popover: ""; }>>Attrs to spread on the content element (id, popover)
contentStyles
Readonly<Ref<Record<string, string>, Record<string, string>>>Styles to spread on the content element (positioning)