@rozie-ui/popover-vue

@rozie-ui/popover-vue

Idiomatic vue Popover — a headless floating primitive for tooltips and popovers, wrapping @floating-ui/dom for collision-aware positioning (offset / flip / shift / arrow) with live autoUpdate tracking. You bring the anchor (the anchor slot) and the floating content (the default slot); Popover owns placement, the open/close gesture (trigger: click / hover / focus), dismissal (Escape + click-outside), the WAI-ARIA wiring (tooltip vs dialog), and a two-way open model — compiled from one Rozie source. Every visual value is a CSS custom property, so it re-skins to any design system. This package is generated; do not edit src/ by hand.

Install

npm i @rozie-ui/popover-vue @floating-ui/dom

Peer dependencies: vue + @floating-ui/dom. Install them alongside this package.

Required peers — beyond the framework peer above, this package requires these non-optional peers to actually render:

• @floating-ui/dom ^1.7.2 — required by @rozie-ui/popover-vue

Install the whole chain in one line:

npm i @rozie-ui/popover-vue @floating-ui/dom

Also installed: @rozie/runtime-vue — Rozie's small, tree-shaken runtime helper package (controllable state, keyboard navigation, event modifiers, and safe interpolation). It arrives as a regular dependency, so npm pulls it for you. Your bundler keeps only the helpers this component actually uses — typically a few hundred bytes to a few KB, minified and gzipped. What's in it and what it costs.

Usage

<script setup lang="ts">
import { ref } from 'vue';
import Popover from '@rozie-ui/popover-vue';

const open = ref(false);
</script>

<template>
  <Popover v-model:open="open" trigger="click" placement="bottom" :offset="8" arrow>
    <template #anchor="{ open, toggle, panelId }">
      <button @click="toggle" :aria-expanded="open" :aria-controls="panelId">Menu</button>
    </template>
    <div>Floating content</div>
  </Popover>
</template>

Positioning against an external element

Pass reference to position the panel against an element you own (or a Floating UI virtual element, e.g. a pointer position) instead of the built-in anchor. Use trigger="manual", drive open yourself, and put the trigger ARIA on your own element. aria-controls points at idBase + '-panel'. A click on the referenced element is not an outside click, so your toggle closes the panel. The outside-click dismissal is decided after your own handlers run, so a handler that repoints reference at another element it was clicked on (keeping open true) moves the panel there. If the referenced element leaves the document while open, the panel closes.

<script setup lang="ts">
import { ref } from 'vue';
import Popover from '@rozie-ui/popover-vue';

const open = ref(false);
const target = ref<HTMLElement | null>(null);
const onClick = (e: MouseEvent) => {
  target.value = e.currentTarget as HTMLElement;
  open.value = !open.value;
};
</script>

<template>
  <button :aria-expanded="open" aria-controls="details-popover-panel" @click="onClick">Details</button>
  <Popover v-model:open="open" trigger="manual" :reference="target" id-base="details-popover">
    <div>About this item</div>
  </Popover>
</template>

Layout

The .rozie-popover root is display: contents, so Popover adds no box of its own: the anchor wrapper sits in the flow and the panel floats. A class or style you pass reaches the root, which is enough for inherited properties (color, font, the --rozie-popover-* tokens), but box properties (margin, width, flex, position, grid-area) have nothing to act on there. To place a popover in a flex row or grid, wrap it in your own element and style the wrapper.

Theming

Every visual value is a --rozie-popover-* CSS custom property (background, border, radius, shadow, padding, z-index, max-width, arrow size) — override any of them at any ancestor scope to match your design system.

Props

Events

Imperative handle

Beyond props, the component exposes imperative methods (declared once in the Rozie source via $expose). Grab a handle with the native ref mechanism and call them directly:

<script setup>
import { ref } from 'vue';
const pop = ref();          // template ref
</script>

<template>
  <Popover ref="pop" v-model:open="open"> ... </Popover>
  <button @click="pop.show()">Open</button>
  <button @click="pop.reposition()">Reposition</button>
</template>

Slots