usePopover

A composable for native popover API behavior with CSS anchor positioning.

Copy Markdown

PreviewIntermediateJun 29, 2026

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.

vue

<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`)
`openDelay`	`MaybeRefOrGetter<number>`	`0`	Milliseconds to wait before opening the popover
`closeDelay`	`MaybeRefOrGetter<number>`	`0`	Milliseconds to wait before closing the popover

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
`cancel()`	-	Cancel any pending open or close transition
`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

A custom account menu built directly on usePopover, without the compound Popover component. The composable owns the popover instance and the menu data, the presentational component renders the trigger and the panel, and the entry wires them together and reports the chosen action. This is the shape to reach for when you want full control over a menu, select, or combobox surface rather than the slots and transitions of Popover.

The example exercises the full three-part spread that usePopover returns. anchorStyles goes on the trigger, where it sets the CSS anchor-name the panel positions against; contentAttrs goes on the panel and applies its id plus the native popover attribute; and contentStyles carries the CSS anchor-positioning rules — position-anchor, position-area, and the position-try-fallbacks produced by positionTry: 'flip-block', which lets the browser flip the panel above the trigger when there is no room below, with no JavaScript position math. Because contentAttrs registers an auto popover, the browser handles light dismiss for free: clicking outside or pressing Escape closes the panel.

MenuButton.vue calls attach(content) with a template ref to the panel element. That single call wires the native toggle event back into isOpen, so when the browser closes the popover on light dismiss the reactive state stays in sync. Selecting an item calls close() and records the choice; the trigger reads isOpen to rotate its caret. For the close-on-outside-click behavior wired manually rather than through the native popover, see useClickOutside; the open and close delays come from useDelay.

File	Role
`useMenu.ts`	Creates the popover, owns the menu items, and closes on select
`MenuButton.vue`	Renders the trigger and panel; calls `attach` to sync native state
`menu-button.vue`	Wires the composable to the component and shows the chosen action

Open the menu and choose an action. Click outside or press Escape to dismiss.

FAQ

Discord

Need help? Join our community for support and discussions ↗

API Reference

The following API details are for the usePopover composable.

usePopover

1 function, 6 options, 5 properties, 5 methods