Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Overlays

Popover

A non-modal panel for a few interactive controls.

Last changed in version 0.13.0: Add avatar groups and chips, expand the block gallery, and improve component colors, spacing, and motion.

Interactive showcase

Install

Run in your project
bunx --bun @getweini/cli@latest add popover

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Vue
<script setup lang="ts">
import Button from './components/ui/button/Button.vue'
import Popover from './components/ui/popover/Popover.vue'
import PopoverContent from './components/ui/popover/PopoverContent.vue'
import PopoverTrigger from './components/ui/popover/PopoverTrigger.vue'
</script>

<template>
  <Popover>
    <PopoverTrigger>View options</PopoverTrigger>
    <PopoverContent aria-label="View options">
      <template #default="{ close }">
        <p>Choose settings for this page.</p>
        <Button @click="close()">Done</Button>
      </template>
    </PopoverContent>
  </Popover>
</template>

Compose trigger and content directly. The panel uses the same triangle and 12px spacing as other anchored overlays. The trigger has visible hover, focus, and open states. Escape closes and restores trigger focus.

When to use it

Inline settings

Show a few controls beside their trigger without blocking the rest of the page.

Small form

Collect a short value and close after the action completes.

More examples

View preferences

The content slot provides a close function.

View preferences
<script setup lang="ts">
import { ref } from 'vue'
import Button from './components/ui/button/Button.vue'
import Popover from './components/ui/popover/Popover.vue'
import PopoverContent from './components/ui/popover/PopoverContent.vue'
import PopoverTrigger from './components/ui/popover/PopoverTrigger.vue'

const compact = ref(false)
</script>
<template>
  <Popover>
    <PopoverTrigger>View options</PopoverTrigger>
    <PopoverContent aria-label="View options">
      <template #default="{ close }">
        <label><input v-model="compact" type="checkbox"> Compact rows</label>
        <Button @click="close()">Done</Button>
      </template>
    </PopoverContent>
  </Popover>
</template>

Controlled details

The parent can open or close a popover through v-model:open.

Controlled details
<script setup lang="ts">
import { ref } from 'vue'
import Popover from './components/ui/popover/Popover.vue'
import PopoverContent from './components/ui/popover/PopoverContent.vue'
import PopoverTrigger from './components/ui/popover/PopoverTrigger.vue'

const open = ref(false)
</script>
<template>
  <Popover v-model:open="open" side="top" align="end">
    <PopoverTrigger>Project details</PopoverTrigger>
    <PopoverContent aria-label="Project details"><p>Last edited today.</p></PopoverContent>
  </Popover>
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

Popover

Complete API for Popover
NameType or signatureDefaultWhat it does
labelpropstring | undefinedNot setVisible or accessible name for this item.
widthpropnumber | undefined320Choose the width of this content.
gappropnumber | undefined12Space in pixels between the trigger and floating content.
alignprop"start" | "end" | "center" | undefined"start"Choose how content aligns within its container.
sideprop"top" | "bottom" | undefined"bottom"Choose the side on which this content appears.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
openmodelboolean | undefinedfalseCurrent open state. Use v-model:open to keep it in sync with your page.
update:openevent[value: boolean]—Requests a new open value from the parent.
triggerslot{ props: OverlayTriggerProps; open: boolean; }OptionalContent for the trigger area of Popover.
defaultslot{ close: (restoreFocus?: boolean) => void; }OptionalContent shown inside Popover.
closeexposed(restoreFocus?: boolean) => void—Close this component from application code.
openexposed() => void—Open this component from application code.

PopoverContent

Complete API for PopoverContent
NameType or signatureDefaultWhat it does
defaultslot{ close: (restoreFocus?: boolean | undefined) => void; }OptionalContent shown inside PopoverContent.

PopoverTrigger

Complete API for PopoverTrigger
NameType or signatureDefaultWhat it does
asChildpropboolean | undefinedNot setUse one child element as the control instead of adding another wrapper.
defaultslot{}OptionalContent shown inside PopoverTrigger.
Public type definitions
Public types
// packages/frameworks/vue/components/popover/types.ts
// ------- TYPES -------

export interface PopoverProps {
  label?: string
  width?: number
  gap?: number
  align?: 'start' | 'center' | 'end'
  side?: 'top' | 'bottom'
  disabled?: boolean
}

export interface PopoverTriggerProps {
  asChild?: boolean
}

Implementation notes

  • Popover is non-modal; background controls remain available.
  • Its panel remains in the local subtree, so avoid clipped or transformed ancestors.

Accessibility and localization

  • Name PopoverContent with aria-label or another suitable relationship.
  • Escape closes and returns focus to the trigger; outside interaction closes without stealing focus.

Source contract and editing guidance