Welcome to Vanilla Breeze
This bell pulls live notifications from /go/notify/messages — the same contract documented at /docs/concepts/service-contracts/. Static articles like this one are the no-JS / no-backend fallback.
pop-over
General-purpose anchored popover container. Wraps the native Popover API with CSS Anchor Positioning, JS fallback, and cascade-layer-aware hiding.
Overview
The <pop-over> component is a thin primitive over the native Popover API. It applies the popover attribute, wires CSS Anchor Positioning when supported, falls back to JS-driven fixed positioning otherwise, and re-asserts display: none under VB's authored cascade layers (where the UA hiding rule loses to authored styles).
It's the consolidation target for the anchored-positioning machinery currently special-cased in <tool-tip> and intended to underpin <context-menu>, <drop-down>, <selection-menu>, and <combo-box>.
Attributes
| Attribute | Type | Default | Description |
|---|---|---|---|
data-mode |
enum | auto |
Popover dismissal: auto (light-dismiss + ESC), manual (script-only), hint (auto + hint stack). |
data-anchor |
string | — | ID or selector of the anchor element. If omitted, the component finds the first element with popovertarget pointing at this pop-over. |
data-position |
enum | bottom |
Placement relative to anchor: top | bottom | left | right, each with optional -start/-end alignment. |
data-offset |
enum | xs |
Gap between popover and anchor: none, xs, s, m, l (mapped to --size-* tokens). |
Imperative API
.show()/.hide()/.toggle()— proxy to the native Popover API..open(getter) — true while the popover is open.- Events:
pop-over:showandpop-over:hidebubble on toggle.
Usage
Standard trigger via popovertarget
HTML
<button popovertarget="prefs">Preferences</button><pop-over id="prefs" data-position="bottom-start"> <p>Pop content here.</p></pop-over>Manual mode (script controls)
HTML
<pop-over id="dialog" data-mode="manual" data-position="top">…</pop-over><script> const p = document.getElementById('dialog'); p.show(); p.addEventListener('pop-over:hide', () => console.log('closed'));</script>Progressive Enhancement
- HTML. The host has the
popoverattribute when authored explicitly, so even without script the browser hides it by default and shows it viapopovertargetbuttons. - CSS. When the browser supports CSS Anchor Positioning (Chromium 125+, Safari TP), positioning is fully declarative — no script runs on resize/scroll.
- JS. The component manages mode, anchor wiring, and a fixed-position fallback for browsers without anchor positioning.
Why a primitive
VB had popover-API logic special-cased inside tool-tip only. As context-menu, drop-down, selection-menu, and combo-box all need the same behavior — including the cascade-layer display: none re-assertion — having one primitive avoids re-implementing positioning, light-dismiss, and the cascade gotcha in five places.