Vben Modal
Vben Modal is the shared modal wrapper used by the framework. It supports draggable behavior, fullscreen mode, auto-height handling, loading state, connected components, and an imperative API.
Basic Usage
const [Modal, modalApi] = useVbenModal({
// props
// events
});
Current Usage Notes
- If you use
connectedComponent, the inner and outer components share data through modalApi.setData() and modalApi.getData().
- When
connectedComponent is present, avoid pushing extra modal props through the connected side. Prefer useVbenModal(...) or modalApi.setState(...).
- Default modal behavior can be adjusted in
apps/<app>/src/bootstrap.ts through setDefaultModalProps(...).
Key Props
| Prop |
Description |
Type |
appendToMain |
mount inside the main content area instead of body |
boolean |
connectedComponent |
connect an inner component to the modal wrapper |
Component |
animationType |
modal enter/leave animation |
'slide' | 'scale' |
fullscreenButton |
show or hide the fullscreen toggle |
boolean |
overlayBlur |
blur amount for the overlay |
number |
submitting |
lock modal interactions while submitting |
boolean |
Events
| Event |
Description |
Type |
onBeforeClose |
called before close; returning false or rejecting prevents close |
() => Promise<boolean | undefined> | boolean | undefined |
onOpenChange |
called when open state changes |
(isOpen: boolean) => void |
onOpened |
called after open animation completes |
() => void |
onClosed |
called after close animation completes |
() => void |
modalApi
| Method |
Description |
setState(...) |
updates modal state |
open() |
opens the modal |
close() |
closes the modal |
setData(data) |
stores shared data |
getData<T>() |
reads shared data |
lock(isLocked = true) |
locks the modal into submitting state |
unlock() |
alias for lock(false) |