useModalAction

Imperative modal API for opening custom components in an overlay shell.

Introduction

useModalAction opens modals imperatively with any Vue or React component as content—typically a Card. The Modal shell (overlay, portal, backdrop, transitions) is rendered by BridgeModalHost.

Use this when you need to open overlays from business logic, nested components, or callbacks without threading show state through props.

Use the framework selector in the site header to switch between React and Vue.

Import

import { BridgeUIHosts } from "@bridge-ui/vue/Actions";
import { useModalAction } from "@bridge-ui/vue/Actions";

import { BridgeUIHosts } from "@bridge-ui/react/Actions";
import { useModalAction } from "@bridge-ui/react/Actions";

Setup

Caution

Mount BridgeUIHosts with BridgeModalHost inside BridgeUIProvider. Without the host, open() will not show a modal. See useDialogAction for a full layout example.

Basic usage

Pass a component and props to open(). The returned id is passed to close(id) from your content or page logic.

Configure the shell with modal: size, blur, transition, align, persistent, and autoFocus.

Component props

The props object is forwarded to your content component—use it for titles, form state, or onClose callbacks.

autoFocus

Set modal.autoFocus: true to focus the first focusable element when the modal opens.

close / closeTop / stack

Imperative modals stack like dialogs. Use close(id), closeTop(), and inspect stackSize / isOpen(id).

Callbacks

onClose and onClosed on open() fire for every dismiss path, including overlay clicks and close(id).

onClose / onClosed counts: 0 / 0

update

Call update(id, { props, modal }) to patch content or shell options on an open modal.

persistent

With modal.persistent: true, only explicit actions in your content dismiss the modal.

Nested stack

Modal content can call useModalAction() again to open another layer on top.

API

Method / property	Description
open(options)	Opens a modal with component and props. Returns an entry id.
close(id)	Closes the entry with the given id.
closeTop()	Closes the topmost entry in the stack.
update(id, patch)	Patches component props and/or modal shell options.
isOpen(id)	Whether the entry is currently open.
stackSize	Number of open modal entries.

open options

Option	Type	Description
component	Component	Content component rendered inside the modal panel.
props	object	Props passed to the content component.
modal	ModalOptions	Shell: size, blur, transition, persistent, autoFocus, etc.
onClose	() => void	Called when a dismiss starts.
onClosed	() => void	Called after the leave animation.

Modal, Card, useDialogAction