Edit or explore something beside its trigger.
A popover keeps a small task close to the thing it belongs to. Put fields, buttons, or other interactive content inside; it handles placement, focus, and dismissal.
<script setup lang="ts">
import { Field, FieldLabel } from "@ui-sdk/vue/field"
import { Input } from "@ui-sdk/vue/input"
import {
Popover,
PopoverClose,
PopoverContent,
PopoverDescription,
PopoverTitle,
PopoverTrigger,
} from "@ui-sdk/vue/popover"
</script>
<template>
<Popover>
<PopoverTrigger>Share</PopoverTrigger>
<PopoverContent>
<PopoverTitle>Share this document</PopoverTitle>
<PopoverDescription>Anyone with the link can view it.</PopoverDescription>
<Field>
<FieldLabel>Link</FieldLabel>
<Input readonly default-value="acme.app/d/q3-roadmap" />
</Field>
<div data-slot="row">
<PopoverClose>Cancel</PopoverClose>
<PopoverClose data-variant="solid">Copy Link</PopoverClose>
</div>
</PopoverContent>
</Popover>
</template>Installation
npm install @ui-sdk/vue @ui-sdk/coreComposition
Use the following composition to build a Popover:
Popover
├── PopoverTrigger
└── PopoverContent
├── PopoverArrow
├── PopoverTitle
├── PopoverDescription
└── PopoverCloseThe content has the dialog role. Its title names it and its description adds context. The arrow is optional, and a popover can have several Close parts. The trigger can live inside the popover or connect from elsewhere.
Usage
Import the parts and put them together:
<script setup lang="ts">
import {
Popover,
PopoverClose,
PopoverContent,
PopoverDescription,
PopoverTitle,
PopoverTrigger,
} from "@ui-sdk/vue/popover"
</script>
<template>
<Popover>
<PopoverTrigger>Share</PopoverTrigger>
<PopoverContent>
<PopoverTitle>Share this document</PopoverTitle>
<PopoverDescription>Anyone with the link can view it.</PopoverDescription>
<PopoverClose>Done</PopoverClose>
</PopoverContent>
</Popover>
</template>Forms
An ordinary form can save a value and then close the popover. Focus starts on the first field and returns to the trigger when the task finishes. A form with method="dialog" closes on submission and returns its submit button's value; the row editor shows that version.
<script setup lang="ts">
import { Field, FieldLabel } from "@ui-sdk/vue/field"
import { Input } from "@ui-sdk/vue/input"
import {
Popover,
PopoverClose,
PopoverContent,
PopoverDescription,
PopoverTitle,
PopoverTrigger,
} from "@ui-sdk/vue/popover"
import { ref } from "vue"
import { useLog } from "./log"
const log = useLog()
const open = ref(false)
function onSubmit(event: Event) {
log(
`Saved ${new FormData(event.currentTarget as HTMLFormElement).get("name")}`
)
open.value = false
}
</script>
<template>
<Popover v-model:open="open">
<PopoverTrigger>Edit Profile</PopoverTrigger>
<PopoverContent>
<PopoverTitle>Edit profile</PopoverTitle>
<PopoverDescription>Your name shows on your posts.</PopoverDescription>
<form data-slot="stack" @submit.prevent="onSubmit">
<Field>
<FieldLabel>Name</FieldLabel>
<Input name="name" required default-value="Hollis Grant" />
</Field>
<div data-slot="row">
<PopoverClose>Cancel</PopoverClose>
<button type="submit" data-variant="solid">Save</button>
</div>
</form>
</PopoverContent>
</Popover>
</template>Keep It Open While Editing
Set dismissible to false while there is unsaved work. Escape and outside presses then keep the popover open and report @dismiss-attempt, so you can ask whether to discard it. Focus leaving is refused quietly. The trigger, Close parts, and controller can still close it.
<script setup lang="ts">
import { Field, FieldControl, FieldLabel } from "@ui-sdk/vue/field"
import {
Popover,
PopoverClose,
PopoverContent,
PopoverDescription,
PopoverTitle,
PopoverTrigger,
} from "@ui-sdk/vue/popover"
import { ref } from "vue"
import { useLog } from "./log"
const log = useLog()
const open = ref(false)
const note = ref("")
const asking = ref(false)
let field: HTMLTextAreaElement | undefined
function close() {
open.value = false
note.value = ""
asking.value = false
}
function onInput(event: Event) {
field = event.target as HTMLTextAreaElement
note.value = field.value
}
function onDismissAttempt(details: { reason: string }) {
log(`Kept open (${details.reason})`)
asking.value = true
}
function keepEditing() {
asking.value = false
field?.focus()
}
function discard() {
log("Discarded the note")
close()
}
function save() {
log(note.value ? "Saved the note" : "Nothing to save")
close()
}
</script>
<template>
<Popover
:open="open"
:dismissible="note === ''"
@update:open="(next: boolean) => (next ? (open = true) : close())"
@dismiss-attempt="onDismissAttempt"
>
<PopoverTrigger>Add Note</PopoverTrigger>
<PopoverContent>
<PopoverTitle>Add a note</PopoverTitle>
<PopoverDescription>Only your team can see it.</PopoverDescription>
<Field>
<FieldLabel>Note</FieldLabel>
<FieldControl :value="note" @input="onInput">
<template #render="{ props }">
<textarea
v-bind="props"
placeholder="Call the printer about the proofs."
/>
</template>
</FieldControl>
</Field>
<div v-if="asking" data-slot="row" role="alert">
Discard your note?
<div data-slot="row">
<button type="button" data-size="sm" @click="keepEditing">
Keep Editing
</button>
<button
type="button"
data-size="sm"
data-variant="solid"
@click="discard"
>
Discard
</button>
</div>
</div>
<div v-else data-slot="row">
<PopoverClose>Cancel</PopoverClose>
<button type="button" data-variant="solid" @click="save">Save</button>
</div>
</PopoverContent>
</Popover>
</template>Placement
side chooses an edge of the trigger, bottom by default, and align lines the popover up with its start, center, or end. Start and end follow text direction. The popover flips or shifts when the requested position doesn't fit, and data-side and data-align report where it landed. The popup guide covers the shared positioning options.
<script setup lang="ts">
import { CheckIcon, ChevronDownIcon } from "@lucide/vue"
import {
Popover,
PopoverContent,
PopoverDescription,
PopoverTitle,
PopoverTrigger,
} from "@ui-sdk/vue/popover"
import {
Select,
SelectContent,
SelectItem,
SelectItemIndicator,
SelectLabel,
SelectTrigger,
SelectValue,
} from "@ui-sdk/vue/select"
import { ref } from "vue"
const sides = [
{ value: "top", label: "Top" },
{ value: "right", label: "Right" },
{ value: "bottom", label: "Bottom" },
{ value: "left", label: "Left" },
]
const aligns = [
{ value: "start", label: "Start" },
{ value: "center", label: "Center" },
{ value: "end", label: "End" },
]
type Side = "top" | "right" | "bottom" | "left"
type Align = "start" | "center" | "end"
const side = ref<Side>("bottom")
const align = ref<Align>("center")
</script>
<template>
<div data-slot="stack">
<div data-slot="controls">
<Select
:items="sides"
:value="side"
@value-change="(next) => next && (side = next as Side)"
>
<SelectLabel>Side</SelectLabel>
<SelectTrigger>
<SelectValue />
<ChevronDownIcon aria-hidden="true" />
</SelectTrigger>
<SelectContent>
<SelectItem
v-for="option in sides"
:key="option.value"
:value="option.value"
>
{{ option.label }}
<SelectItemIndicator>
<CheckIcon aria-hidden="true" />
</SelectItemIndicator>
</SelectItem>
</SelectContent>
</Select>
<Select
:items="aligns"
:value="align"
@value-change="(next) => next && (align = next as Align)"
>
<SelectLabel>Align</SelectLabel>
<SelectTrigger>
<SelectValue />
<ChevronDownIcon aria-hidden="true" />
</SelectTrigger>
<SelectContent>
<SelectItem
v-for="option in aligns"
:key="option.value"
:value="option.value"
>
{{ option.label }}
<SelectItemIndicator>
<CheckIcon aria-hidden="true" />
</SelectItemIndicator>
</SelectItem>
</SelectContent>
</Select>
</div>
<Popover>
<PopoverTrigger>Delivery</PopoverTrigger>
<PopoverContent :side="side" :align="align" :side-offset="8">
<PopoverTitle>Delivery window</PopoverTitle>
<PopoverDescription
>Arrives Tuesday between 9 AM and noon.</PopoverDescription
>
</PopoverContent>
</Popover>
</div>
</template>Offsets
side-offset is the gap to the trigger, 4 pixels by default. align-offset shifts the popover along the trigger's edge, and collision-padding is the space kept from the edges of the window.
<script setup lang="ts">
import { CheckIcon, ChevronDownIcon } from "@lucide/vue"
import {
Popover,
PopoverContent,
PopoverDescription,
PopoverTitle,
PopoverTrigger,
} from "@ui-sdk/vue/popover"
import {
Select,
SelectContent,
SelectItem,
SelectItemIndicator,
SelectLabel,
SelectTrigger,
SelectValue,
} from "@ui-sdk/vue/select"
import { reactive } from "vue"
const choices = {
sideOffset: { label: "Side offset", values: ["4", "8", "16", "24"] },
alignOffset: { label: "Align offset", values: ["-16", "0", "16"] },
collisionPadding: { label: "Collision padding", values: ["8", "24", "48"] },
}
type Name = keyof typeof choices
const offsets = reactive<Record<Name, string>>({
sideOffset: "8",
alignOffset: "0",
collisionPadding: "8",
})
</script>
<template>
<div data-slot="stack">
<div data-slot="controls">
<Select
v-for="(choice, name) in choices"
:key="name"
:items="choice.values"
:value="offsets[name]"
@value-change="(next) => next && (offsets[name] = next)"
>
<SelectLabel>{{ choice.label }}</SelectLabel>
<SelectTrigger>
<SelectValue />
<ChevronDownIcon aria-hidden="true" />
</SelectTrigger>
<SelectContent>
<SelectItem
v-for="value in choice.values"
:key="value"
:value="value"
>
{{ value }}px
<SelectItemIndicator>
<CheckIcon aria-hidden="true" />
</SelectItemIndicator>
</SelectItem>
</SelectContent>
</Select>
</div>
<Popover>
<PopoverTrigger>Delivery</PopoverTrigger>
<PopoverContent
align="start"
:side-offset="Number(offsets.sideOffset)"
:align-offset="Number(offsets.alignOffset)"
:collision-padding="Number(offsets.collisionPadding)"
>
<PopoverTitle>Delivery window</PopoverTitle>
<PopoverDescription
>Arrives Tuesday between 9 AM and noon.</PopoverDescription
>
</PopoverContent>
</Popover>
</div>
</template>Arrow
PopoverArrow follows the side the popover actually uses, including after a flip, and gets the same data-side. arrow-padding keeps it away from the corners; data-arrow-clamped tells you when it can't point at the middle of the trigger. This example cancels dismissal when you press its side buttons, so the open arrow can move.
<script setup lang="ts">
import { CircleQuestionMarkIcon } from "@lucide/vue"
import type { ChangeDetails } from "@ui-sdk/core"
import {
Popover,
PopoverArrow,
PopoverContent,
PopoverDescription,
PopoverTitle,
PopoverTrigger,
} from "@ui-sdk/vue/popover"
import { ref } from "vue"
const sides = [
{ value: "top", label: "Top" },
{ value: "right", label: "Right" },
{ value: "bottom", label: "Bottom" },
{ value: "left", label: "Left" },
] as const
type Side = (typeof sides)[number]["value"]
const open = ref(false)
const side = ref<Side>("bottom")
const controls = ref<HTMLElement | null>(null)
function onOpenChange(next: boolean, details: ChangeDetails) {
const target = details.event?.target
const inControls = target instanceof Node && controls.value?.contains(target)
if (inControls && details.reason !== "escape-key") {
return details.cancel()
}
open.value = next
}
</script>
<template>
<div data-slot="stack">
<div ref="controls" data-slot="controls" role="group" aria-label="Side">
<button
v-for="option in sides"
:key="option.value"
type="button"
data-size="sm"
:aria-pressed="side === option.value"
@click="side = option.value"
>
{{ option.label }}
</button>
</div>
<Popover :open="open" @open-change="onOpenChange">
<PopoverTrigger aria-label="Help">
<CircleQuestionMarkIcon aria-hidden="true" />
</PopoverTrigger>
<PopoverContent :side="side" :side-offset="10" :arrow-padding="12">
<PopoverArrow />
<PopoverTitle>Keyboard shortcuts</PopoverTitle>
<PopoverDescription
>Press ? anywhere to see them all.</PopoverDescription
>
</PopoverContent>
</Popover>
</div>
</template>Keep overflow visible around an arrow that extends outside the panel. If the body needs to scroll, put scrolling on an inner element. You can also draw an arrow with ::before, using data-side and --arrow-offset to position it.
Anchor
Set anchor to position against something other than the trigger. It accepts an element, a selector, a point such as { x, y }, or an object with getBoundingClientRect(), such as a text range. The position is read again as the anchor moves.
<script setup lang="ts">
import { CheckIcon, SlidersHorizontalIcon } from "@lucide/vue"
import { Checkbox, CheckboxIndicator } from "@ui-sdk/vue/checkbox"
import {
Popover,
PopoverClose,
PopoverContent,
PopoverDescription,
PopoverTitle,
PopoverTrigger,
} from "@ui-sdk/vue/popover"
import { ref } from "vue"
const types = [
{ label: "Documents", checked: true },
{ label: "Images", checked: false },
{ label: "Shared with me", checked: true },
]
const anchor = ref<HTMLInputElement | null>(null)
</script>
<template>
<div data-slot="row">
<input
ref="anchor"
type="search"
placeholder="Search files…"
aria-label="Search files"
/>
<Popover>
<PopoverTrigger aria-label="Search filters">
<SlidersHorizontalIcon aria-hidden="true" />
</PopoverTrigger>
<PopoverContent :anchor="anchor" align="start" :side-offset="8">
<PopoverTitle>Filters</PopoverTitle>
<PopoverDescription>Show only these kinds of files.</PopoverDescription>
<div data-slot="stack">
<label v-for="type in types" :key="type.label" data-slot="label">
<Checkbox :default-checked="type.checked">
<CheckboxIndicator>
<CheckIcon aria-hidden="true" />
</CheckboxIndicator>
</Checkbox>
{{ type.label }}
</label>
</div>
<div data-slot="row">
<PopoverClose>Cancel</PopoverClose>
<PopoverClose data-variant="solid">Apply</PopoverClose>
</div>
</PopoverContent>
</Popover>
</div>
</template>Modal
modal controls how the popover shares the page:
false, the default, leaves the page usable, and focus leaving the popover closes it."trap-focus"keeps Tab inside while the page can still scroll and receive clicks.truealso makes the rest of the page inert and locks scrolling.
<script setup lang="ts">
import { CheckIcon, ChevronDownIcon } from "@lucide/vue"
import { Field, FieldLabel } from "@ui-sdk/vue/field"
import { Textarea } from "@ui-sdk/vue/textarea"
import {
Popover,
PopoverClose,
PopoverContent,
PopoverDescription,
PopoverTitle,
PopoverTrigger,
} from "@ui-sdk/vue/popover"
import {
Select,
SelectContent,
SelectItem,
SelectItemIndicator,
SelectLabel,
SelectTrigger,
SelectValue,
} from "@ui-sdk/vue/select"
import { computed, ref } from "vue"
const modes = [
{ value: "false", label: "Non-modal" },
{ value: "trap-focus", label: "Trap focus" },
{ value: "true", label: "Modal" },
]
type Mode = "false" | "trap-focus" | "true"
const notes = {
false: "Tab can leave, and focus leaving closes it.",
"trap-focus": "Tab stays inside. The page still scrolls and takes clicks.",
true: "Tab stays inside. The page is inert and doesn't scroll.",
}
const mode = ref<Mode>("false")
const modal = computed(() =>
mode.value === "true" ? true : mode.value === "false" ? false : "trap-focus"
)
</script>
<template>
<div data-slot="stack">
<div data-slot="controls">
<Select
:items="modes"
:value="mode"
@value-change="(next) => next && (mode = next as Mode)"
>
<SelectLabel>Modal</SelectLabel>
<SelectTrigger>
<SelectValue />
<ChevronDownIcon aria-hidden="true" />
</SelectTrigger>
<SelectContent>
<SelectItem
v-for="option in modes"
:key="option.value"
:value="option.value"
>
{{ option.label }}
<SelectItemIndicator>
<CheckIcon aria-hidden="true" />
</SelectItemIndicator>
</SelectItem>
</SelectContent>
</Select>
</div>
<Popover :modal="modal">
<PopoverTrigger>Add Comment</PopoverTrigger>
<PopoverContent>
<PopoverTitle>Add a comment</PopoverTitle>
<PopoverDescription>{{ notes[mode] }}</PopoverDescription>
<Field>
<FieldLabel>Comment</FieldLabel>
<Textarea default-value="Looks good to me." />
</Field>
<div data-slot="row">
<PopoverClose>Cancel</PopoverClose>
<PopoverClose data-variant="solid">Comment</PopoverClose>
</div>
</PopoverContent>
</Popover>
</div>
</template>Focus
Use initial-focus to choose the first focused element, or "none" to leave focus where it is. final-focus controls where focus returns. Opening on hover leaves focus alone; opening with touch focuses the panel itself so no on-screen keyboard appears. See popup focus for the shared focus rules.
<script setup lang="ts">
import { Field, FieldLabel } from "@ui-sdk/vue/field"
import { Input } from "@ui-sdk/vue/input"
import {
Popover,
PopoverClose,
PopoverContent,
PopoverDescription,
PopoverTitle,
PopoverTrigger,
} from "@ui-sdk/vue/popover"
</script>
<template>
<div data-slot="row">
<Popover>
<PopoverTrigger>Rename</PopoverTrigger>
<PopoverContent>
<PopoverTitle>Rename file</PopoverTitle>
<PopoverDescription
>Focus starts in the first field.</PopoverDescription
>
<Field>
<FieldLabel>Name</FieldLabel>
<Input default-value="Q3 roadmap.pdf" />
</Field>
<div data-slot="row">
<PopoverClose>Cancel</PopoverClose>
<PopoverClose data-variant="solid">Save</PopoverClose>
</div>
</PopoverContent>
</Popover>
<Popover>
<PopoverTrigger>Publish</PopoverTrigger>
<PopoverContent initial-focus="[data-autofocus]">
<PopoverTitle>Publish changes?</PopoverTitle>
<PopoverDescription
>Focus starts on Publish, not Cancel.</PopoverDescription
>
<div data-slot="row">
<PopoverClose>Cancel</PopoverClose>
<PopoverClose data-autofocus="" data-variant="solid"
>Publish</PopoverClose
>
</div>
</PopoverContent>
</Popover>
<Popover>
<PopoverTrigger>Status</PopoverTrigger>
<PopoverContent initial-focus="none" final-focus="none">
<PopoverTitle>All systems normal</PopoverTitle>
<PopoverDescription>Focus stays on the trigger.</PopoverDescription>
</PopoverContent>
</Popover>
</div>
</template>Open on Hover
open-on-hover adds pointer opening while keeping click, keyboard, and touch activation. delay and close-delay control the pause before opening and closing. You can cross the gap into the content and interact with it.
<script setup lang="ts">
import {
Popover,
PopoverArrow,
PopoverContent,
PopoverDescription,
PopoverTitle,
PopoverTrigger,
} from "@ui-sdk/vue/popover"
import { useLog } from "./log"
const log = useLog()
</script>
<template>
<Popover open-on-hover :delay="200" :close-delay="150">
<PopoverTrigger>@kofi</PopoverTrigger>
<PopoverContent :side-offset="8">
<PopoverArrow />
<PopoverTitle>Kofi Mensah</PopoverTitle>
<PopoverDescription
>Engineering manager, platform team.</PopoverDescription
>
<div data-slot="row">
<button
type="button"
data-size="sm"
data-variant="solid"
@click="log('Followed @kofi')"
>
Follow
</button>
</div>
</PopoverContent>
</Popover>
</template>Controlled
Use v-model:open to keep the popover's state in your component. Cancel a proposed change with details.cancel() in @open-change. See state and events for the common change contract.
<script setup lang="ts">
import { CheckIcon } from "@lucide/vue"
import type { ChangeDetails } from "@ui-sdk/core"
import { Checkbox, CheckboxIndicator } from "@ui-sdk/vue/checkbox"
import { Field, FieldLabel } from "@ui-sdk/vue/field"
import { Input } from "@ui-sdk/vue/input"
import {
Popover,
PopoverClose,
PopoverContent,
PopoverDescription,
PopoverTitle,
PopoverTrigger,
} from "@ui-sdk/vue/popover"
import { ref } from "vue"
import { useLog } from "./log"
const log = useLog()
const open = ref(false)
const controls = ref<HTMLElement | null>(null)
function onOpenChange(next: boolean, details: ChangeDetails) {
const target = details.event?.target
const inControls = target instanceof Node && controls.value?.contains(target)
if (inControls && details.reason !== "escape-key") {
return details.cancel()
}
log(`${next ? "Opened" : "Closed"} (${details.reason})`)
}
</script>
<template>
<div data-slot="stack">
<div ref="controls" data-slot="controls">
<label data-slot="label">
<Checkbox
:checked="open"
@checked-change="(next) => (open = next === true)"
>
<CheckboxIndicator>
<CheckIcon aria-hidden="true" />
</CheckboxIndicator>
</Checkbox>
Open
</label>
</div>
<Popover v-model:open="open" @open-change="onOpenChange">
<PopoverTrigger>Set Status</PopoverTrigger>
<PopoverContent>
<PopoverTitle>Set a status</PopoverTitle>
<PopoverDescription
>Your team sees it next to your name.</PopoverDescription
>
<Field>
<FieldLabel>Status</FieldLabel>
<Input default-value="In a meeting" />
</Field>
<div data-slot="row">
<PopoverClose>Cancel</PopoverClose>
<PopoverClose data-variant="solid">Save</PopoverClose>
</div>
</PopoverContent>
</Popover>
</div>
</template>Keyboard Shortcut
Set a trigger's shortcut to toggle the popover from the keyboard. mod+i means Command+I on Apple platforms and Control+I elsewhere. The Shortcut part displays the platform's keys, and the trigger advertises them through aria-keyshortcuts.
<script setup lang="ts">
import { Field, FieldLabel } from "@ui-sdk/vue/field"
import { Input } from "@ui-sdk/vue/input"
import {
Popover,
PopoverClose,
PopoverContent,
PopoverDescription,
PopoverShortcut,
PopoverTitle,
PopoverTrigger,
} from "@ui-sdk/vue/popover"
</script>
<template>
<Popover>
<PopoverTrigger shortcut="mod+i">
Invite
<PopoverShortcut />
</PopoverTrigger>
<PopoverContent>
<PopoverTitle>Invite people</PopoverTitle>
<PopoverDescription
>They'll get an email with a link to join.</PopoverDescription
>
<Field>
<FieldLabel>Email</FieldLabel>
<Input type="email" placeholder="wren@example.com" />
</Field>
<div data-slot="row">
<PopoverClose>Cancel</PopoverClose>
<PopoverClose data-variant="solid">Send Invite</PopoverClose>
</div>
</PopoverContent>
</Popover>
</template>Triggers Outside the Popover
Connect the triggers and popover to one createPopoverController<Member>(). Each trigger passes its row as payload; the content reads the active row from its state. Only the active trigger is expanded and receives focus back. Opening from another row updates the same panel, so one editor can serve the whole list.
controller.open({ payload, anchor }) opens it from code and returns a promise with the closing reason and any returnValue. The payload stays available during the exit animation. See controllers for the shared pattern.
<script setup lang="ts">
import { Field, FieldControl, FieldLabel } from "@ui-sdk/vue/field"
import {
createPopoverController,
Popover,
PopoverContent,
PopoverDescription,
PopoverTitle,
PopoverTrigger,
} from "@ui-sdk/vue/popover"
import { computed, ref } from "vue"
import { useLog } from "./log"
type Member = { name: string; role: string }
const roles = ["Admin", "Editor", "Viewer"]
const log = useLog()
const popover = createPopoverController<Member>()
const MemberPopoverContent = PopoverContent<Member>
const members = ref<Member[]>([
{ name: "Hollis Grant", role: "Owner" },
{ name: "Inès Moreau", role: "Editor" },
{ name: "Kofi Mensah", role: "Viewer" },
{ name: "Wren Takahashi", role: "Viewer" },
])
const newest = computed(() => members.value[members.value.length - 1])
async function editNewest(event: MouseEvent) {
const result = await popover.open({
payload: newest.value,
anchor: event.currentTarget as HTMLElement,
})
log(`Closed (${result.reason}), returned ${result.returnValue ?? "nothing"}`)
}
function onPayloadChange(payload: unknown) {
const member = payload as Member | undefined
if (member) {
log(`Editing ${member.name}`)
}
}
function save(event: SubmitEvent, member: Member | undefined) {
if ((event.submitter as HTMLButtonElement).value !== "save" || !member) {
return
}
const role = String(
new FormData(event.currentTarget as HTMLFormElement).get("role")
)
members.value = members.value.map((entry) =>
entry.name === member.name ? { ...entry, role } : entry
)
}
</script>
<template>
<div data-slot="stack">
<div data-slot="controls">
<button type="button" @click="editNewest">Edit Newest Member</button>
</div>
<ul data-slot="list">
<li v-for="member in members" :key="member.name" data-slot="row">
{{ member.name }}
<span data-slot="hint">{{ member.role }}</span>
<PopoverTrigger
:controller="popover"
:payload="member"
:disabled="member.role === 'Owner'"
data-size="sm"
data-variant="ghost"
:aria-label="`Edit ${member.name}`"
>
Edit
</PopoverTrigger>
</li>
</ul>
<Popover :controller="popover" @payload-change="onPayloadChange">
<MemberPopoverContent v-slot="{ state }" align="end" :side-offset="8">
<PopoverTitle>{{ state.payload?.name }}</PopoverTitle>
<PopoverDescription
>Roles decide what they can change.</PopoverDescription
>
<form
data-slot="stack"
method="dialog"
@submit="save($event as SubmitEvent, state.payload)"
>
<Field>
<FieldLabel>Role</FieldLabel>
<FieldControl
:key="state.payload?.name"
name="role"
:default-value="state.payload?.role"
>
<template #render="{ props }">
<select v-bind="props">
<option v-for="role in roles" :key="role">{{ role }}</option>
</select>
</template>
</FieldControl>
</Field>
<div data-slot="row">
<button type="submit" value="cancel" formnovalidate>Cancel</button>
<button type="submit" value="save" data-variant="solid">
Save
</button>
</div>
</form>
</MemberPopoverContent>
</Popover>
</div>
</template>Animation
The content has data-starting-style while it opens and data-ending-style while it closes. Transition from those states, and the popover stays mounted until the exit finishes. @open-change-complete runs after the transition, and keep-mounted keeps the closed content in the page, hidden. See styling and animation for the common lifecycle.
<script setup lang="ts">
import {
Popover,
PopoverClose,
PopoverContent,
PopoverDescription,
PopoverTitle,
PopoverTrigger,
} from "@ui-sdk/vue/popover"
import { useLog } from "./log"
const log = useLog()
</script>
<template>
<Popover
@open-change="(open: boolean) => log(open ? 'Opening' : 'Closing')"
@open-change-complete="(open: boolean) => log(open ? 'Open' : 'Closed')"
>
<PopoverTrigger>What's New</PopoverTrigger>
<PopoverContent keep-mounted>
<PopoverTitle>What's new</PopoverTitle>
<PopoverDescription
>Comments now support threads and reactions.</PopoverDescription
>
<div data-slot="row">
<PopoverClose data-variant="solid">Got It</PopoverClose>
</div>
</PopoverContent>
</Popover>
</template>Presentation
presentation="sheet" shows the task as a sheet; "auto" chooses a sheet on small touch screens each time it opens. A sheet is modal by default and can be swiped down to dismiss. If dismissal is disabled, it springs back and reports the attempt.
Style data-presentation for both layouts. The sheet manages its own position and movement, so leave its translation alone and avoid the floating panel's fixed width. --sheet-backdrop sets the dim behind it.
<script setup lang="ts">
import { Field, FieldLabel } from "@ui-sdk/vue/field"
import { Input } from "@ui-sdk/vue/input"
import {
Popover,
PopoverClose,
PopoverContent,
PopoverDescription,
PopoverTitle,
PopoverTrigger,
} from "@ui-sdk/vue/popover"
</script>
<template>
<Popover presentation="sheet">
<PopoverTrigger>Add Reminder</PopoverTrigger>
<PopoverContent>
<PopoverTitle>New reminder</PopoverTitle>
<PopoverDescription
>We'll notify you at the time you pick.</PopoverDescription
>
<Field>
<FieldLabel>Remind me to</FieldLabel>
<Input default-value="Send the Q3 roadmap" />
</Field>
<div data-slot="row">
<PopoverClose>Cancel</PopoverClose>
<PopoverClose data-variant="solid">Save</PopoverClose>
</div>
</PopoverContent>
</Popover>
</template>Container
Popovers render in place by default and use the browser's top layer. container moves their DOM to another element while keyboard order still follows the trigger. See popups for the shared container behavior.
<script setup lang="ts">
const container = useTemplateRef<HTMLDivElement>("container")
</script>
<template>
<div ref="container" />
<Popover>
<PopoverTrigger>Details</PopoverTrigger>
<PopoverContent :container="container">...</PopoverContent>
</Popover>
</template>Custom Rendering
Every part takes a render slot, which receives the props to bind and the part's state, and the default slot receives the state too. The content's default slot can read its payload, as the row editor does.
<script setup lang="ts">
import {
Popover,
PopoverClose,
PopoverContent,
PopoverDescription,
PopoverShortcut,
PopoverTitle,
PopoverTrigger,
} from "@ui-sdk/vue/popover"
</script>
<template>
<Popover>
<PopoverTrigger shortcut="mod+u">
<template #render="{ props, state }">
<button v-bind="props">
{{ state.open ? "Hide Updates" : "Show Updates" }}
<PopoverShortcut v-slot="{ state: shortcut }">{{
shortcut.text
}}</PopoverShortcut>
</button>
</template>
</PopoverTrigger>
<PopoverContent>
<PopoverTitle>
<template #render="{ props }">
<h3 v-bind="props">Updates</h3>
</template>
</PopoverTitle>
<PopoverDescription
>Version 2.4 adds threaded comments.</PopoverDescription
>
<PopoverClose>
<template #render="{ props }">
<a v-bind="props" href="#">Read the Changelog</a>
</template>
</PopoverClose>
</PopoverContent>
</Popover>
</template>Styling
Use data-open on the trigger to mark it while its popover shows, and data-side and data-align to style the content and arrow for where they landed. Put transform-origin: var(--transform-origin) on the content so a scale animation starts from the trigger.
Each part has a data-slot, such as popover-content, and its state attributes are listed under Data Attributes.
PopoverContent
| Variable | What it holds |
|---|---|
--anchor-width | Width of the anchor, usually the trigger. Use it to match widths. |
--anchor-height | Height of the anchor. |
--available-width | Space beside the popup, up to the viewport edge. Not inherited either. |
--available-height | Space between the anchor and the viewport edge. Use it for max-height. Not inherited, so a child that needs it copies it on the popup, like [--list-height:var(--available-height)], and reads max-h-(--list-height). The first popup registers both names for the whole page with CSS.registerProperty, so they don't inherit anywhere. A page that needs them to inherit calls it first, with inherits: true. An @property rule can't, since a registration in script wins. |
--transform-origin | The point on the anchor the popup opens from. Use it to scale from the right place. |
--arrow-offset | Where the anchor's center falls along the popup's edge, kept arrowPadding from the corners. Position a ::before arrow with it. |
--drawer-progress | While it presents as a sheet: how far open the sheet is, from 0 closed to 1 at its largest snap point. Never past 1. |
--drawer-dim | While it presents as a sheet: how dim the page behind is, from 0 to 1. The backdrop's opacity follows it. |
--drawer-expand | While it presents as a sheet: 0 at the second-largest snap point and below, 1 at the largest. With one snap point, the whole travel. |
--drawer-stack | While it presents as a sheet: how many sheets opened from inside this one are open above it, rising smoothly as each one opens. Push it back with it. |
--sheet-backdrop | Set it yourself: the color the page dims to while it presents as a sheet. Black at 0.2 by default. |
Viewport
| Variable | What it holds |
|---|---|
--keyboard-inset | While it presents as a sheet: how many pixels of the page the on-screen keyboard covers, 0 without one. |
--visual-viewport-width | While it presents as a sheet: the width of the part of the page you can see. |
--visual-viewport-height | While it presents as a sheet: the height of the part of the page you can see, above the keyboard. |
--visual-viewport-top | While it presents as a sheet: how far the part of the page you can see is scrolled from the top of the layout, as when the keyboard pushes it up. |
Data Attributes
PopoverTitle, PopoverDescription and PopoverClose have no state attributes.
PopoverTrigger
[data-slot="popover-trigger"]
| Attribute | What it means |
|---|---|
data-closed | Present while the popover is closed, including while it animates out. |
data-disabled | Present when the trigger is disabled. |
data-open | Present while the popover is open. On a trigger, while it's open from that trigger. |
PopoverContent
[data-slot="popover-content"]
| Attribute | What it means |
|---|---|
data-closed | Present while the popover is closed, including while it animates out. |
data-presentation | popoversheetHow the popover presents this time it's open. |
data-open | Present while the popover is open. On a trigger, while it's open from that trigger. |
data-starting-style | Present for the first frame. Style the state you animate from. |
data-ending-style | Present while the popover animates out. Style the state you animate to. |
PopoverArrow
[data-slot="popover-arrow"]
| Attribute | What it means |
|---|---|
data-closed | Present while the popover is closed, including while it animates out. |
data-open | Present while the popover is open. On a trigger, while it's open from that trigger. |
API Reference
Props are the same as below, and callbacks are events.
Popover
container?DocumentFragment | Element | null- Renders the popup into this element instead of in place, like a container inside a shadow root or an iframe. On web components, a CSS selector. Nested popups stay inside their parent.
open?boolean- Whether the popover is open. Pass it to control the popover.
defaultOpen?boolean- Whether the popover starts open, when uncontrolled.
@open-change((open: boolean, details: ChangeDetails<PopoverOpenChangeReason>) => void)- Runs when the popover wants to open or close.
details.reasonsays why, anddetails.cancel()stops it. @open-change-complete((open: boolean) => void)- Runs once the popover has finished opening or closing, after any animation.
@payload-change((payload: unknown, details: ChangeDetails<PopoverPayloadChangeReason>) => void)- Runs when the payload the content shows changes: a trigger with another payload opens the popover, or takes the open popover over, which fires no
@open-change, and so does a controller'sopen({ payload })on the open popover.details.cancel()keeps the previous payload. modal?"trap-focus" | booleanfalse: the rest of the page stays usable, and focus leaving the popover closes it.true: also traps focus, locks scroll and makes the rest of the page inert, and an outside press only closes the popover."trap-focus": traps focus but leaves the page scrollable and clickable.openOnHover?boolean- Whether resting the pointer on the trigger opens the popover. Pressing the trigger still opens it, so keyboard and touch users can too.
delay?number- Milliseconds the pointer rests on the trigger before the popover opens, with
openOnHover. closeDelay?number- Milliseconds before the popover closes once the pointer leaves it and its trigger, with
openOnHover. presentation?PresentationSetting<"popover">- How the popover presents.
"sheet"slides it up from the bottom of the screen, where it can be swiped away, and"auto"does that on small touch screens. Decided each time it opens; the server renders"popover"for"auto". controller?PopupController<any, PopoverOpenChangeReason, {}, string, PopoverPayloadChangeReason>- Opens, closes and inspects the popover from anywhere, and connects triggers outside it. Create one with
createPopoverController(). dismissible?boolean- Whether Escape, an outside press, focus or the window leaving, Android's back gesture and a sheet's swipe can close it. Triggers, Close parts and the controller always can. Pass
falsewhile it holds unsaved work, and ask in@dismiss-attempt. @dismiss-attemptfunction- Runs when
dismissiblerefused a dismissal made on purpose: Escape, an outside press, back or a swipe. Focus or the window leaving is refused without it. Ask "Discard changes?" here. debug?boolean- Logs every state change with its reason to the console, in development builds.
PopoverTrigger
A trigger outside the popover also takes controller.
disabled?boolean- Stops the trigger from opening the popover. A native button can't be focused or pressed, unless
focusableWhenDisabledis set. focusableWhenDisabled?boolean- Keeps a disabled trigger in the tab order with
aria-disabledinstead of the native attribute, so it can host a tooltip that says why. Presses still do nothing. payload?unknown- Data for the content to render when this trigger opens the popover, like the row it belongs to.
shortcut?string- A keyboard shortcut that presses the trigger, like
"mod+i".modis Command on Apple platforms and Control elsewhere. Setsaria-keyshortcuts. controller?PopupController<any, PopoverOpenChangeReason, {}, string, PopoverPayloadChangeReason>- Connects a trigger outside the popover, like one per table row, to the popover with this controller.
PopoverContent
side?Side- Which side of the anchor the popup opens on. Flips to the other side when there isn't room. Which side of the trigger the popover opens on.
align?Align- How the popup lines up with the anchor along that side.
startandendfollow the reading direction. How the popover lines up with the trigger along that side. sideOffset?number- Gap between the anchor and the popup, in pixels. Gap between the trigger and the popover, in pixels.
alignOffset?number- Shift along the anchor, in pixels. Shift along the trigger, in pixels.
collisionPadding?number- Space to keep from the viewport edges, in pixels.
arrowPadding?number- Space to keep between the arrow and the popup's corners, in pixels.
anchor?string | Anchor | null- Positions the popup against this instead of its trigger: an element, a CSS selector, a point like
{ x, y }, or anything withgetBoundingClientRect(). It's read on every check, so it can move. A controller'sopen({ anchor })wins for that open. container?DocumentFragment | Element | null- Renders the popup into this element instead of in place, like a container inside a shadow root or an iframe. On web components, a CSS selector. Nested popups stay inside their parent.
initialFocus?PopoverInitialFocus- Where focus goes when the popover opens. Opening on hover never moves focus, and opening with touch focuses the popover itself so no on-screen keyboard appears.
finalFocus?PopupFocusTarget- Where focus goes when the popover closes while focus is inside it.
keepMounted?boolean- Whether the popover stays in the page, hidden, while closed. For animation libraries that drive the exit from state.
PopoverArrow
Points at the trigger from the side the popover landed on. Renders a div.
PopoverTitle
Names the popover. Renders an h2.
PopoverDescription
Describes the popover while it's rendered. Renders a p.
PopoverClose
Closes the popover. Renders a button.
PopoverShortcut
shortcut?string- The keys to show. Inside a trigger, its
shortcut.
State
What render functions, state-based class names and slots receive, per part.
PopoverTrigger:
openboolean- Whether the popover is open from this trigger.
disabledboolean- Set by the trigger's
disabledprop, which stops it opening the popover.
PopoverContent:
openboolean- Whether the popover is open. False while it animates out.
modalboolean | "trap-focus"- The
modalsetting. presentation"popover" | "sheet"- How it presents this time it's open.
payloadPayload | undefined- The payload of the last open, from the trigger that opened it or a controller, typed as the controller's
Payload.
PopoverArrow:
openboolean- Whether the popover is open. False as soon as it starts closing, while it still animates out.
PopoverShortcut:
textstring- The shortcut formatted for this platform:
⌘Ion Apple platforms andCtrl+Ielsewhere. Empty without one.
Reasons
details.reason says why the popover opened or closed.
trigger-pressMouseEvent | KeyboardEvent | TouchEvent- Click, tap, Enter or Space on the part that opens, closes or toggles. Arrow keys that open a menu or submenu count too. A tap on a combobox's input that opens a sheet reports its
touchend. trigger-hoverPointerEvent- The pointer rested on a trigger, or left it, with hover opening.
outside-pressMouseEvent- A press outside the layer.
escape-keyKeyboardEvent- Escape, or a submenu's close key (ArrowLeft in left-to-right layouts).
focus-outKeyboardEvent | FocusEvent- Focus left the layer, or Tab moved it out.
window-blurFocusEvent- The window lost focus.
close-pressMouseEvent | KeyboardEvent | SubmitEvent- A Close part was pressed, or a form with
method="dialog"was submitted. backEvent- Going back: the Android back button or gesture, or Backspace in an empty command input, which returns to the previous page.
shortcutKeyboardEvent- A keyboard shortcut, like a trigger's
shortcut. swipeTouchEvent | PointerEvent- A swipe gesture: a finger, mouse or pen dragged it.
imperativenone- A controller or
apicall, or a property set on a web component.
For a payload change, it says what opened the popover or took it over.
trigger-pressMouseEvent | KeyboardEvent | TouchEvent- Click, tap, Enter or Space on the part that opens, closes or toggles. Arrow keys that open a menu or submenu count too. A tap on a combobox's input that opens a sheet reports its
touchend. trigger-hoverPointerEvent- The pointer rested on a trigger, or left it, with hover opening.
shortcutKeyboardEvent- A keyboard shortcut, like a trigger's
shortcut. imperativenone- A controller or
apicall, or a property set on a web component.
With dismissible false, the refused dismissals @dismiss-attempt reports:
outside-pressMouseEvent- A press outside the layer.
escape-keyKeyboardEvent- Escape, or a submenu's close key (ArrowLeft in left-to-right layouts).
backEvent- Going back: the Android back button or gesture, or Backspace in an empty command input, which returns to the previous page.
swipeTouchEvent | PointerEvent- A swipe gesture: a finger, mouse or pen dragged it.
Controller
Create one with createPopoverController<Payload>() and pass it as controller, to the popover and to any
triggers outside it. Payload is the type of the data triggers and open() pass.
Every write method takes an optional { reason, event }, passed to @open-change.
isOpen()() => boolean- Whether it's open. False as soon as it starts closing, while it still animates out.
setOpen(open, options?)(open: boolean, options?: PopupChangeOptions<PopoverOpenChangeReason> | undefined) => boolean- Opens or closes it. Returns false when the change was canceled or it was already open or closed.
open(options?)(options?: (PopupChangeOptions<PopoverPayloadChangeReason> & { payload?: Payload | undefined; anchor?: Anchor | undefined; signal?: AbortSignal | undefined; }) | undefined) => Promise<...>- Opens it, and resolves once it closes, with why, how and any return value. Resolves exactly once and never rejects: on the next close from any source, when
signalaborts, or with reason"unmount"when the component leaves the page. close(options?)(options?: (PopupChangeOptions<PopoverOpenChangeReason> & { returnValue?: Result | undefined; }) | undefined) => boolean- Closes it.
returnValueis passed to the promiseopen()returned. Returns false when the close was canceled or it was already closed. toggle(options?)(options?: PopupChangeOptions<PopoverOpenChangeReason> | undefined) => boolean- Opens it when it's closed, and closes it when it's open. Returns false when the change was canceled.
getPayload()() => Payload | undefined- The payload of the last open, from a controller or the trigger that opened it.
focus()() => void- Moves focus to the trigger that opened it last, or the first trigger.
Events
Events get the new state first, then the details. v-model only updates when @open-change wasn't canceled.
| Binding | On | Receives |
|---|---|---|
v-model:open | Popover | Whether the popover is open |
@open-change | Popover | (open, details): the new state, and the reason |
@open-change-complete | Popover | (open), after the animation |
@payload-change | Popover | (payload, details): the content's new payload, and the reason |
@dismiss-attempt | Popover | ({ reason, event }), when a dismissal was refused |
Accessibility
The trigger is a button that opens a dialog, and focus inside follows the WAI-ARIA dialog pattern.
Tested Behavior
Every line below is an automated test.
- Reflects the open state.
- Click opens the popover.
- Click on the open trigger closes the popover.
- Enter opens the popover.
- Space opens the popover.
- Points to the popover it controls while open.
- Opening moves focus to the first focusable element.
- Each time focus moves in, the popover is named by its title and described by its description.
- Tab moves through the popover in order.
- Shift+Tab from the first element returns focus to the trigger.
- Tab from the last element moves focus to the element after the trigger.
- Focus leaving the popover closes it.
- Escape closes the popover and returns focus to the trigger.
- Escape after a click returns focus to the trigger.
- The close button closes the popover and returns focus to the trigger.
- With initial focus none, opening leaves focus on the trigger.
- A virtual click from a screen reader moves focus into the popover.
- A touch press focuses the popover itself, so no on-screen keyboard appears.
- Closing after the trigger is gone moves focus to the element after where it was.
- Pressing a button inside keeps the popover open.
- Clicking outside closes the popover.
- Clicking inside the popover keeps it open.
- An outside press reaches what it hits.
- A press on empty space returns focus to the trigger.
- Escape while an input method is composing text leaves the popover open.
- Pressing a scrollbar outside the popover leaves it open.
- Pressing a button in a shadow root inside keeps the popover open.
- Tab into a button in a shadow root inside keeps the popover open.
- Escape on a button in a shadow root inside returns focus to the trigger.
- Switching windows leaves the popover open.
- With modal true, Tab stays inside the popover.
- With modal trap-focus, Tab stays inside the popover.
- With modal true, an outside press only closes the popover.
- With modal true, the page doesn't scroll while open.
- Resting the pointer on the trigger opens the popover.
- Moving the pointer into the popover keeps it open.
- Moving the pointer away closes the popover.
- Opening on hover leaves focus where it was.
- Keyboard focus on the trigger doesn't open the popover.
- Escape on a popover opened by hover leaves focus where it was.
- Pressing the trigger still opens the popover.
- Using a nested popover keeps both open.
- Escape closes only the nested popover and returns focus to its trigger.
- Clicking outside closes every popover.
Runs in React, Vue and web components.
Additional behaviors:
- The popup writes --arrow-offset, where the trigger's center falls along its edge.
- Without a title, the trigger names the popover.
- Tab from the trigger of a popover opened by hover moves into it.
- A controller opens the popover from anywhere and moves focus in.
- A popover open from the start leaves focus alone.
- Modal popovers make the rest of the page inert and restore it exactly.
- Live regions keep announcing while a modal popover makes the page inert.
- Clicking into an iframe closes the popover.
- An infinite exit animation still unmounts.
- A trigger's shortcut opens and closes the popover.
- The trigger advertises its shortcut, and its Shortcut part shows the keys to sighted users only.
- A Shortcut part shows its own keys.
- A trigger connected through a controller shows and binds its own shortcut.
- A title added after the popover connects names it. Web components only.
- Changing an attribute updates the part. Web components only.
Runs in React, Vue and web components.
Screen readers hear the same thing in each tested framework, recorded by a virtual screen reader:
- Announcements while using the popover with a keyboard.
Runs in React, Vue and web components.