vue-modal: Instructions file for Codex

@kolirt/vue-modal — guide for AI agents

This is a complete, de-styled offline reference for AI coding agents using @kolirt/vue-modal (Vue 3 headless modal library). Canonical, always-current docs live at https://kolirt.github.io/vue-modal/. Package version: 2.4.0.

If you only read one section, read this one.

Critical rules (avoid the common mistakes)

• Peer deps: requires vue >= 3.4 and reka-ui >= 2. Install both.
• Register the plugin: app.use(createModal({ groups: { default: {} } })).
• Mount a target: put <ModalTarget group="default" /> in your app layout (not behind a v-if that is false when a modal opens).
• Hierarchy: a modal component must render <ModalRoot> wrapping <ModalContent>. Missing <ModalContent> ⇒ the modal is blank and never closes (the exit animation never fires).
• Group is required: openModal(Comp, { group: 'default' }), or declare defineOptions({ modalGroup: 'default' }) on the component. No group ⇒ throws.
• Never call openModal at module scope. Call it from an event handler or inside onMounted. It is client-only; it mutates shared module-level state, so calling it during SSR is unsafe (the state leaks across concurrent requests).
• z-index / stacking: <ModalTarget> has no built-in z-index. Within one group the package stacks modals for you, but to order different groups (a confirm/prompt above a main modal) give each group's <ModalTarget> an explicit z-index — a small layered scale (z-40…z-70), not 9999. Same if a page's fixed element overlaps the modal. (See the z-index section.)
• SSR: the component primitives are SSR-safe and render on the server; openModal is not — only call it on the client (e.g. inside onMounted).

Minimal correct setup

// main.ts
import { createModal } from '@kolirt/vue-modal'
app.use(createModal({ groups: { default: {} } }))

<!-- App.vue -->
<template>
  <RouterView />
  <ModalTarget group="default" />
</template>