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
});

vue

<script lang="ts" setup>
import { useVbenModal, VbenButton } from '@vben/common-ui';

const [Modal, modalApi] = useVbenModal();
</script>
<template>
  <div>
    <VbenButton @click="() => modalApi.open()">Open</VbenButton>
    <Modal class="w-150" title="基础示例"> modal content </Modal>
  </div>
</template>

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)`

Contributors

xingyu4j

Changelog

Last edited 10 days ago

View full history

Vben Modal ​

Basic Usage ​

Current Usage Notes ​

Key Props ​

Events ​

modalApi ​