Types

All types below are exported from @kolirt/vue-modal and can be imported directly:

import type { ModalHandle, OpenModalOptions, ModalBehaviorOptions } from '@kolirt/vue-modal'

ModalGroupRegistry

export interface ModalGroupRegistry {}

An empty interface that acts as the central registry for all group names in your application. Extend it via declare module augmentation to register group keys. Every other type that references ModalGroup is constrained to keys in this registry.

// src/modal-groups.ts
declare module '@kolirt/vue-modal' {
  interface ModalGroupRegistry {
    default: unknown
    confirm: unknown
    preview: unknown
  }
}

See Groups for the full workflow.

ModalGroup

export type ModalGroup = keyof ModalGroupRegistry

A union of every key registered in ModalGroupRegistry. Using an unregistered string where ModalGroup is expected is a TypeScript error.

DefineGroups<T>

export type DefineGroups<T extends readonly (string | number | symbol)[]> = {
  [K in T[number]]: unknown
}

Convenience helper that expands a const tuple of group names into the shape required by ModalGroupRegistry. Use it to avoid repeating key names:

const GROUPS = ['default', 'confirm', 'preview'] as const

declare module '@kolirt/vue-modal' {
  interface ModalGroupRegistry extends DefineGroups<typeof GROUPS> {}
}

ModalGroupsConfig

export type ModalGroupsConfig = {
  [K in ModalGroup]?: ModalBehaviorOptions
}

The map accepted by createModal({ groups }). Each registered group may optionally supply a ModalBehaviorOptions object to override the hardcoded defaults. See Plugin for usage.

ModalBehaviorOptions

export interface ModalBehaviorOptions {
  enableInteractOutside?: boolean
  disableCloseOnInteractOutside?: boolean
  disableCloseOnInteractOverlay?: boolean
  disableLockBodyScroll?: boolean
  disableCloseOnEscape?: boolean
}

Behavior flags that can be supplied at three layers: createModal({ groups }), <ModalTarget> props, and the hardcoded defaults. Higher-priority layers win. All fields are optional; omitted fields fall through to the next layer.

See Behavior options for the cascade logic and full examples.

ModalEffectiveOptions

export interface ModalEffectiveOptions {
  interactOutside: boolean
  closeOnInteractOutside: boolean
  closeOnInteractOverlay: boolean
  lockBodyScroll: boolean
  closeOnEscape: boolean
}

The resolved, positive-form options for a single modal after cascading group config, target props, and defaults. Exposed via useModalContext().effectiveOptions as a ComputedRef<ModalEffectiveOptions>. See Composables.

OpenModalOptions<C>

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

Options passed to openModal or useModal().open().

CloseModalOptions<T>

export interface CloseModalOptions<T = unknown> {
  success?: boolean
  data?: T
  ignoreGuard?: boolean
  instantExit?: boolean
}

Options accepted by closeModal, closeModalById, and ModalHandle.close(). closeAllModals and closeModalsByGroup accept only { ignoreGuard?, instantExit? } — they do not forward success / data.

CloseManyResult

export interface CloseManyResult {
  closed: number
  vetoed: number
}

The resolved value of the promises returned by closeAllModals and closeModalsByGroup. closed counts modals that began closing; vetoed counts those whose onBeforeClose guards returned false while ignoreGuard was not set.

ExtractComponentProps<C>

export type ExtractComponentProps<C> = C extends new () => { $props: infer P }
  ? Omit<P, keyof VNodeProps | keyof AllowedComponentProps>
  : Record<string, unknown>

Utility type that extracts the user-facing props of a Vue component C, stripping internal Vue props (key, ref, class, style, etc.). Used to type OpenModalOptions.props.

ModalHandle<T>

export interface ModalHandle<T = unknown> 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
}

The return value of openModal. Extends Promise<T> so it is directly awaitable. The extra fields allow you to interact with the open instance without awaiting.

ModalItem

export interface ModalItem {
  id: number
  group: ModalGroup
  component: Component
  props: Record<string, unknown>
  listeners: Record<string, (...args: any[]) => void>
}

The public read-only shape of a stack entry. Exposed via modals and groupModals. Mutations to these objects are ignored — use the close/confirm APIs instead.

BeforeCloseHandler

export type BeforeCloseHandler = () => boolean | void | Promise<boolean | void>

The signature expected by useModalContext().onBeforeClose(handler). Return false (or Promise<false>) to veto the close; return void/true/undefined to allow it. See Composables.

CreateModalOptions

export interface CreateModalOptions {
  groups?: ModalGroupsConfig
}

The single options object accepted by createModal. See Plugin for full documentation and the install snippet.

ModalTargetProps

export interface ModalTargetProps extends ModalBehaviorOptions {
  group: ModalGroup
}

Props of the <ModalTarget> component. Inherits the five optional flags from ModalBehaviorOptions plus a required group.

ModalRootProps

export interface ModalRootProps {}

Props of the <ModalRoot> component. Empty by design — all behavior options live on <ModalTarget> or in createModal({ groups }).