---
name: popover-usage
description: >
Use after component-usage-ux when an app needs @techsio/ui-kit Popover for
anchored non-blocking content using Zag.js compound parts, placement,
portalling, close behavior, arrow, title, description, and close trigger.
metadata:
component_version: "2.0.0"
type: "core"
library: "@techsio/ui-kit"
library_version: "0.3.2"
requires: "component-usage-ux zag-compound-components app-token-overrides ux-guidelines"
resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md"
sources: "https://zagjs.com/components/react/popover"
contributor_sources: "libs/ui/src/molecules/popover.tsx libs/ui/src/tokens/components/molecules/_popover.css libs/ui/stories/molecules/popover.stories.tsx libs/ui/src/molecules/popover.figma.ts"
audience: "consumer"
---
> Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory.
# @techsio/ui-kit Popover Usage
Use Popover for anchored, dismissible content. Use Dialog for modal flows and
Tooltip for tiny supplemental text.
## UX/UI guidelines
House rules come from the `ux-guidelines` skill (writing, formatting, states,
where actions and feedback live). This section applies them to `Popover`.
**Use it when**
- Small interactive content anchored to its trigger: filter panels, colour pickers, quick edit of one value, share options.
**Use something else when**
| Need | Use instead |
| --- | --- |
| A decision that must block the page | Dialog |
| A read-only hint | Tooltip |
| A list of commands | Menu |
| Large forms | Dialog / drawer |
**Do**
- Keep content short; if it scrolls, it should be a dialog.
- End filter popovers with `[Reset] [Apply]` bottom-right, or apply instantly — not both.
- Return focus to the trigger on close; close on Escape and outside click.
**Don't**
- Put required information only in a popover.
- Open popovers on hover.
**Copy and states**
- Trigger text says what opens (`Filters`, `Share`); count active filters in the trigger (`Filters (2)`).
**Behaviour (from the UX spec)**
- Closing (Escape, outside click, close button) never applies a half-made change; an unapplied filter draft is discarded.
- Without a visible title, give `Popover.Content` an `aria-label`; without a close button, Escape and outside click must still close it.
- `placement` is a preference: the kit flips on collision (`flip` defaults to `true`).
**Figma → code**
| Figma | Code |
| --- | --- |
| `showArrow` | `