Api

Functions

openModal, closeModal, closeModalById, closeAllModals, closeModalsByGroup, replaceModal, ModalClosedError.

Functions

All functions are top-level exports from @kolirt/vue-modal. For createModal, see Plugin.

`openModal<T, C>(component, options?) → ModalHandle<T>`

Opens a modal. Returns a Promise-like handle that resolves with T on confirm(data) or rejects with ModalClosedError on close(). The handle is awaitable directly — await openModal(...) unwraps the resolved data.

Signature

function openModal<T = unknown, C extends Component = Component>(
  component: C,
  options?: OpenModalOptions<C>
): ModalHandle<T>

interface OpenModalOptions<C extends Component> {
  props?: ExtractComponentProps<C>
  on?: Record<string, (...args: any[]) => void>
  group?: ModalGroup
  instantEnter?: boolean
}

interface ModalHandle<T> extends Promise<T> {
  id: number
  group: ModalGroup
  close(opts?: CloseModalOptions<T>): void
  on(event: string, handler: (...args: any[]) => void): void
  off(event: string, handler: (...args: any[]) => void): void
}

Parameters

Parameter	Type	Required	Description
`component`	`C extends Component`	yes	The Vue component to mount as a modal. Can be sync, async (`defineAsyncComponent`), or carry a `defineOptions({ modalGroup })` declaration.
`options`	`OpenModalOptions<C>`	no	Open-time configuration. Required only when `component` doesn't declare a group via `defineOptions`. See the Options section below for the full shape.

Type parameters

Param	Default	Meaning
`T`	`unknown`	The type the modal resolves with via `confirm(data)`. Drives the `Promise<T>` return and `ModalHandle<T>`.
`C`	`Component`	Component type — used to infer `props` shape via `ExtractComponentProps<C>`.

import { openModal } from '@kolirt/vue-modal'
import ConfirmDialog from './ConfirmDialog.vue'

const handle = openModal<boolean>(ConfirmDialog, {
  group: 'default',
  props: { message: 'Sure?' },
  on: {
    progress: (n: number) => console.log(n)
  },
  instantEnter: false
})

handle.id // number — instance id
handle.group // ModalGroup
handle.close({ ignoreGuard: true }) // request close (default success: false)
handle.on('done', (v) => console.log(v)) // add listener post-mount
handle.off('done', fn) // remove listener

// or await directly:
const ok = await handle.catch(() => false)

import { useModal } from '@kolirt/vue-modal'
import ConfirmDialog from './ConfirmDialog.vue'

const dialog = useModal<boolean>(ConfirmDialog, {
  group: 'default',
  props: { message: 'Sure?' },
  on: {
    progress: (n: number) => console.log(n)
  }
})

const ok = await dialog.open({ instantEnter: false }).catch(() => false)

// reactive bindings:
dialog.isOpen.value // boolean
dialog.instanceId.value // number | null

Options

Field	Type	Description
`group`	`ModalGroup`	Target group. If omitted, falls back to `defineOptions({ modalGroup })` on the component; otherwise runtime error.
`props`	`ExtractComponentProps<C>`	Typed props for the modal component.
`on`	`Record<string, (...args) => void>`	Event listeners. Names converted Vue-style (`my-event` → `onMyEvent`, `update:value` → `onUpdate:value`).
`instantEnter`	`boolean`	Skip enter animation.

Throws

Synchronously, if group cannot be resolved from options or defineOptions({ modalGroup }). Exact message: [@kolirt/vue-modal] openModal() requires a `group` option (or `defineOptions({ modalGroup: ... })` on the component).

See Types for OpenModalOptions<C>, ModalHandle<T>, and ExtractComponentProps<C>.

`closeModal<T>(opts?) → Promise<void>`

Closes the topmost modal — globally if no group, or topmost of the given group. Returns a promise that resolves when the close has been processed (guards awaited, animation pending or skipped). Accepts CloseModalOptions<T> plus an optional group.

Signature

function closeModal<T = unknown>(
  opts?: CloseModalOptions<T> & { group?: ModalGroup }
): Promise<void>

interface CloseModalOptions<T = unknown> {
  success?: boolean   // false → reject with ModalClosedError, true → resolve with `data`
  data?: T            // value passed to resolve when success: true
  ignoreGuard?: boolean // skip every onBeforeClose guard
  instantExit?: boolean // skip exit animation, finalize synchronously
}

Parameters

Parameter	Type	Required	Description
`opts`	`CloseModalOptions<T> & { group?: ModalGroup }`	no	Inherits all fields from `CloseModalOptions<T>` (`success`, `data`, `ignoreGuard`, `instantExit`) plus an optional `group` to scope the lookup.

await closeModal() // global topmost (rejects)
await closeModal({ group: 'confirm' }) // topmost in 'confirm'
await closeModal({ success: true, data: payload }) // resolve instead of reject
await closeModal({ ignoreGuard: true }) // bypass beforeClose
await closeModal({ instantExit: true }) // skip exit animation

closeModal is the imperative counterpart to the close() returned by useModalContext() inside the modal itself. Inside a modal, prefer the context method — it's bound to the right instance even when other modals open on top.

`closeModalById<T>(id, opts?) → Promise<void>`

Closes the modal with the given id. No-op if no such modal exists. See CloseModalOptions<T>.

Signature

function closeModalById<T = unknown>(
  id: number,
  opts?: CloseModalOptions<T>
): Promise<void>

// CloseModalOptions<T> shape — see closeModal above.

Parameters

Parameter	Type	Required	Description
`id`	`number`	yes	The modal instance id — read from `handle.id` after `openModal`, or from `controller.instanceId.value` returned by `useModal`. Unknown ids are silently ignored.
`opts`	`CloseModalOptions<T>`	no	Same shape as `closeModal`. See `CloseModalOptions<T>`.

const handle = openModal(MyDialog, { group: 'default' })
await closeModalById(handle.id, { ignoreGuard: true })

`closeAllModals(opts?) → Promise<{ closed, vetoed }>`

Closes every open modal across the entire app, in reverse stack order (top-down).

Signature

function closeAllModals(
  opts?: CloseFlags
): Promise<{ closed: number; vetoed: number }>

interface CloseFlags {
  ignoreGuard?: boolean // skip every onBeforeClose guard
  instantExit?: boolean // skip exit animations
}

Parameters

Parameter	Type	Required	Description
`opts`	`CloseFlags`	no	`{ ignoreGuard?: boolean, instantExit?: boolean }`. There is no `success` / `data` — bulk close always rejects each modal's promise. See `CloseFlags`.

The promise resolves to { closed, vetoed } — closed counts modals that began closing; vetoed counts those whose onBeforeClose guards returned false while ignoreGuard was not set.

const { closed, vetoed } = await closeAllModals()
// closed: number of modals successfully closed
// vetoed: number that did not transition to closing (e.g. blocked by a guard)

Closes in reverse stack order (top-down). Only ignoreGuard and instantExit are accepted — there is no success / data for bulk close.

`closeModalsByGroup(group, opts?) → Promise<{ closed, vetoed }>`

Same as closeAllModals but scoped to one group.

Signature

function closeModalsByGroup(
  group: ModalGroup,
  opts?: CloseFlags
): Promise<{ closed: number; vetoed: number }>

// CloseFlags shape — see closeAllModals above.

Parameters

Parameter	Type	Required	Description
`group`	`ModalGroup`	yes	The group key (typed by your `ModalGroupRegistry`). Only modals whose `group` matches are closed; other groups are unaffected.
`opts`	`CloseFlags`	no	Same shape as `closeAllModals` — `{ ignoreGuard?, instantExit? }`. See `CloseFlags`.

`replaceModal<T, C>(component, options?) → ModalHandle<T>`

Closes the current topmost modal of the target group (with ignoreGuard: true, instantExit: true) and opens a new one. Modals in other groups are left untouched. Useful for wizards / dialog chains.

Signature

function replaceModal<T = unknown, C extends Component = Component>(
  component: C,
  options?: OpenModalOptions<C>
): ModalHandle<T>

// OpenModalOptions<C> and ModalHandle<T> shapes — see openModal above.

Parameters

Parameter	Type	Required	Description
`component`	`C extends Component`	yes	The component to mount after the current topmost modal in the target group is closed (`ignoreGuard: true, instantExit: true`).
`options`	`OpenModalOptions<C>`	no	Same shape as `openModal`. The `group` field (or `defineOptions({ modalGroup })` on the component) determines which stack to replace. Throws if neither is set.

Type parameters identical to openModal.

replaceModal(StepTwo, {
  group: 'wizard',
  props: { step: 2 },
  instantEnter: true // skip enter too — feels like one continuous step
})

Target group resolution: options.group ?? component.modalGroup.

Throws

Synchronously, if group cannot be resolved. Exact message: [@kolirt/vue-modal] replaceModal() requires a `group` option (or `defineOptions({ modalGroup: ... })` on the component).

class ModalClosedError extends Error {
  name: 'ModalClosedError'
  message: 'Modal closed.'
}

import { openModal, ModalClosedError } from '@kolirt/vue-modal'
import ConfirmDialog from './ConfirmDialog.vue'

try {
  const ok = await openModal<boolean>(ConfirmDialog, { group: 'default' })
} catch (e) {
  if (e instanceof ModalClosedError) {
    // user dismissed
  } else {
    throw e // propagate
  }
}

Edit this pageorReport an issue

Global error modal

Wire a fetch/axios interceptor to open an error modal from anywhere. Uses a dedicated high-z-index group, replaceModal to deduplicate, and closeModalsByGroup on logout.

Components

ModalTarget, ModalRoot, ModalContent, ModalTitle, ModalDescription, ModalOverlay.

Functions

Functions

`openModal<T, C>(component, options?) → ModalHandle<T>`

Signature

Parameters

Options

Throws

`closeModal<T>(opts?) → Promise<void>`

Signature

Parameters

`closeModalById<T>(id, opts?) → Promise<void>`

Signature

Parameters

`closeAllModals(opts?) → Promise<{ closed, vetoed }>`

Signature

Parameters

`closeModalsByGroup(group, opts?) → Promise<{ closed, vetoed }>`

Signature

Parameters

`replaceModal<T, C>(component, options?) → ModalHandle<T>`

Signature

Parameters

Throws

State inspection

`ModalClosedError`

Signature