https://github.com/kolirt/vue-modal
⚡️ Easy to use and highly customizable Vue3 modal package
https://github.com/kolirt/vue-modal
modal modal-dialog modal-dialogs modal-windows vue vuejs
Last synced: about 1 month ago
JSON representation
⚡️ Easy to use and highly customizable Vue3 modal package
- Host: GitHub
- URL: https://github.com/kolirt/vue-modal
- Owner: kolirt
- License: mit
- Created: 2023-06-28T11:46:50.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2025-03-29T10:17:14.000Z (about 1 year ago)
- Last Synced: 2025-06-04T08:13:20.697Z (about 1 year ago)
- Topics: modal, modal-dialog, modal-dialogs, modal-windows, vue, vuejs
- Language: Vue
- Homepage: https://kolirt.github.io/vue-modal/
- Size: 942 KB
- Stars: 18
- Watchers: 1
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome-vue-3 - @kolirt/vue-modal - Easy to use and highly customizable Vue3 modal package. (Packages)
- awesome-vue - @kolirt/vue-modal - ⚡️ Simple Vue3 modal package (Components & Libraries / UI Components)
- fucking-awesome-vue - @kolirt/vue-modal - ⚡️ Simple Vue3 modal package (Components & Libraries / UI Components)
- awesome-vue - @kolirt/vue-modal - ⚡️ Simple Vue3 modal package (Components & Libraries / UI Components)
README
@kolirt/vue-modal
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.
📚 Documentation ·
🎮 Playground ·
🍳 Recipes
---
## 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.
## 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
import { ModalTarget, ModalOverlay } from '@kolirt/vue-modal'
```
**3. Write a modal:**
```vue
import { ModalRoot, ModalContent, ModalTitle, ModalDescription, useModalContext } from '@kolirt/vue-modal'
defineOptions({ modalGroup: 'default' })
const props = defineProps<{ message: string }>()
const { close, confirm } = useModalContext<boolean>()
Confirm
{{ props.message }}
Cancel
OK
```
> 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).