Open modals from any function, stack them as needed, and style them however you want.
No template boilerplate, no manual state โ just call and await.
---
## What you get
`@kolirt/vue-modal` is a lightweight, headless modal package for Vue 3. It lets you open, stack, and control dialogs imperatively from any function โ without registering modal components in templates or wiring open/close state by hand.
- **Open from JS/TS** โ trigger modals from any function and await the user's response. A single call returns a typed promise with full TypeScript inference for props and result.
- **Less template boilerplate** โ skip placing every modal in your templates and wiring open/close state by hand. Register one mount point and trigger any modal from code with a single call.
- **Cascading modals** โ open multiple modals one after another while preserving their state and context. Layer a confirmation on top of a form without losing the form's data.
- **Highly customizable** โ headless primitives with no imposed styles. Bring your own CSS, transitions, and animations โ compose modals that fit any design system.
- **Modal groups** โ isolate flows with named groups โ the main app stack, confirm dialogs, side panels โ each rendering in its own mount point with its own queue.
- **Async components** โ open any Vue component, including async ones loaded on demand. Heavy modals stay out of your initial bundle and resolve through the same promise.
## ๐ค For AI agents
Using an AI coding agent? See [`AGENTS.md`](./AGENTS.md) for a complete,
de-styled reference plus a critical-rules checklist. The two most common agent
mistakes are a missing `` and z-index/stacking โ both covered there.
## Install
```bash
npm install @kolirt/vue-modal reka-ui
# or
yarn add @kolirt/vue-modal reka-ui
# or
pnpm add @kolirt/vue-modal reka-ui
```
`reka-ui` is a peer dependency.
## Quick start
**1. Register groups and install the plugin** (`main.ts`):
The package requires every modal to belong to a registered group. Without registered groups the package can't be used at all โ there's no implicit `'default'`.
```ts
import { createApp } from 'vue'
import { createModal, type DefineGroups } from '@kolirt/vue-modal'
import App from './App.vue'
// (TypeScript only) Type-check every `group` reference against this list.
declare module '@kolirt/vue-modal' {
interface ModalGroupRegistry extends DefineGroups<['default']> {}
}
const app = createApp(App)
app.use(
createModal({
groups: {
// per-group behavior options โ see /guide/behavior-options for the full list
default: {}
}
})
)
app.mount('#app')
```
**2. Mount a `` for each group** (`App.vue`):
```vue
```
**3. Write a modal:**
```vue
Confirm{{ props.message }}
```
> Styles omitted for brevity. See the [first modal](https://kolirt.github.io/vue-modal/getting-started/first-modal) page for the full version with enter/exit animations.
**4. Open it from anywhere:**
```ts
import { openModal } from '@kolirt/vue-modal'
import ConfirmDialog from './ConfirmDialog.vue'
const ok = await openModal(ConfirmDialog, {
props: { message: 'Delete this project?' }
}).catch(() => false)
if (ok) {
// user pressed OK
}
```
## Documentation
Everything lives at **[kolirt.github.io/vue-modal](https://kolirt.github.io/vue-modal/)**:
- [Getting started](https://kolirt.github.io/vue-modal/getting-started/introduction) โ install, setup, your first modal
- [Concepts](https://kolirt.github.io/vue-modal/concepts/architecture) โ architecture, imperative flow, stacking, groups, headless primitives
- [Guide](https://kolirt.github.io/vue-modal/guide/writing-a-modal) โ writing modals, props & results, behavior options, styling, `useModal`, multiple targets, async components, TypeScript
- [Recipes](https://kolirt.github.io/vue-modal/recipes/confirm-dialog) โ confirm dialog, form with validation, lightbox, command palette, nested flows, global error modal
- [API reference](https://kolirt.github.io/vue-modal/api/functions) โ functions, components, composables, plugin, state, types
- [Migration from v1](https://kolirt.github.io/vue-modal/resources/migration-from-v1) ยท [FAQ](https://kolirt.github.io/vue-modal/resources/faq) ยท [Troubleshooting](https://kolirt.github.io/vue-modal/resources/troubleshooting) ยท [Changelog](https://kolirt.github.io/vue-modal/resources/changelog)
## Support
## License
[MIT](https://github.com/kolirt/vue-modal/blob/master/LICENSE)
## Other packages
Check out my other projects on my [GitHub profile](https://github.com/kolirt).
## License
[MIT](https://github.com/kolirt/vue-modal/blob/master/LICENSE)
## Other packages
Check out my other projects on my [GitHub profile](https://github.com/kolirt).