popup

Positioned popup overlay with anchor-aware placement.

import { html, atom, popup } from 'mates';

const isOpen = atom(false);

// Element directive — attach to the anchor
html`
  <button
    ${popup(
      html`<ul><li>Item A</li><li>Item B</li></ul>`,
      { open: isOpen, position: 'bottom-start', gap: 4 },
    )}
    @click=${() => isOpen.set(v => !v)}
  >
    Menu ▾
  </button>
`;

// Toggle mode (no open atom) — click anchor to open/close:
// html`<button ${popup(html`…`, 'bottom-start')}>Menu</button>`

Overview

popup(content, options?) is an element directive — attach it to the anchor with ${popup(...)}. The panel uses position: fixed, repositions on scroll/resize, and escapes overflow: hidden ancestors.

Toggle mode (default): click the anchor to open/close; outside-click and Escape close automatically. Controlled mode: pass open as a boolean atom — you own open/close (no automatic outside-click / Escape).

For modals and hover tips, use mates-ui (Dialog, tooltip, tip) — they build on portal / popup.

Modes

Mode	open option	Behaviour
Toggle	omit `open`	Click anchor toggles. Outside-click + Escape close.
Controlled	`open: atom`	No click listener. You set the atom; wire dismiss yourself.

Quick reference

// Placement shorthand
html`<button ${popup(html`…`, 'bottom-start')}>Menu</button>`

Attach popup() to the button. Pass an open atom for controlled visibility. The panel floats with position:fixed so it is never clipped by overflow:hidden containers.

import { html, atom, popup, renderApp } from 'mates';

const App = () => {

const open = atom(false);

const selected = atom('Option A');

const menu = html`

${['Option A','Option B','Option C'].map(opt => html`

<button class="btn-ghost btn-block m-t-10"

@click=${() => { selected.set(opt); open.set(false); }}>

${opt}${selected() === opt ? ' ✓' : ''}

</button>

`)}

</div>

return () => html`

<button

class="btn-primary"

${popup(menu, { open, position: 'bottom-start', gap: 8 })}

@click=${() => open.set(v => !v)}

${selected()} ▾

</button>

};

renderApp(App, document.getElementById('app'));

Omit open — click the anchor to toggle. Outside-click and Escape close automatically.

import { html, popup, renderApp } from 'mates';

const menu = html`

</div>

const App = () => () => html`

Toggle menu ▾

</button>

renderApp(App, document.getElementById('app'));

API — popup

import { popup } from 'mates'

Prop / Option	Type	Default	Description
`popup(content, options?)`*	`DirectiveResult`	—	Element directive. content is the floating panel TemplateResult. Second arg may be a Placement string or PopupOptions.
`content`*	`TemplateResult`	—	Floating panel content. Fully reactive — atoms read inside it trigger updates normally.

PopupOptions

Prop / Option	Type	Default	Description
`open`	`boolean \| AtomType`	—	Controlled visibility. When set, no click toggle / outside-click / Escape wiring.
`position`	`Placement`	`'bottom-start'`	top \| bottom \| left \| right (+ -start / -end) \| auto.
`gap`	`number`	`4`	Pixels between anchor edge and panel.
`matchAnchorWidth`	`boolean`	—	Set panel width to match the anchor.
`destroyOnClose`	`boolean`	`false`	Remove the panel from document.body when closed (useful for heavy content).
`onOpen / onClose`	`callbacks`	—	Lifecycle hooks after show / on close.
`zIndex`	`number \| string`	—	Override panel z-index (e.g. above a modal).

Overview

Modes

Quick reference

Anchored dropdown with popup()

Toggle mode (no open atom)