https://github.com/worldzhao/vue-nice-modal
Vue version of @ebay/nice-modal-react
https://github.com/worldzhao/vue-nice-modal
dialog modal promise utility-library vant vue vue-composition-api vue3 vuejs
Last synced: 10 months ago
JSON representation
Vue version of @ebay/nice-modal-react
- Host: GitHub
- URL: https://github.com/worldzhao/vue-nice-modal
- Owner: worldzhao
- Created: 2023-05-20T09:10:18.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2025-03-30T10:52:05.000Z (about 1 year ago)
- Last Synced: 2025-07-04T22:49:07.176Z (11 months ago)
- Topics: dialog, modal, promise, utility-library, vant, vue, vue-composition-api, vue3, vuejs
- Language: JavaScript
- Homepage:
- Size: 258 KB
- Stars: 52
- Watchers: 2
- Forks: 5
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Vue Nice Modal
**Vue version of [@ebay/nice-modal-react](https://github.com/eBay/nice-modal-react).**
vue-nice-modal is a utility library that converts Vue.js modal components into Promise-based APIs.
Supports Vue 2.x via [vue-demi](https://github.com/vueuse/vue-demi).
English | [įŽäŊä¸æ](https://github.com/worldzhao/vue-nice-modal/blob/main/README.zh-CN.md)
An elegant Vue modal state management solution, supporting both Vue 2 and Vue 3.
## Features
- đ¯ Simple and intuitive API
- đ Promise-based modal operations
- đ¨ Framework agnostic - works with any UI library
- âĄī¸ Lightweight, zero dependencies
- đ Supports both Vue 2 and Vue 3
- đĻ Full TypeScript support
## Installation
```bash
# npm
npm install vue-nice-modal
# pnpm
pnpm add vue-nice-modal
```
## Usage
### 1. Wrap application with Provider
```html
import { Provider as NiceModalProvider } from 'vue-nice-modal';
```
### 2. Create modal component
```html
import { useModal } from 'vue-nice-modal';
const modal = useModal();
defineProps(['title', 'content']);
const handleCancel = () => {
modal.reject('cancel');
modal.hide();
};
const handleConfirm = () => {
modal.resolve('confirm');
modal.hide();
};
```
> Can be used with any UI library, such as element-ui
```html
{{ content }}
```
> Create modal higher-order component using NiceModal.create
```js
// my-modal.js
import NiceModal from 'vue-nice-modal';
import _MyModal from './my-modal.vue';
export const MyModal = NiceModal.create(_MyModal);
```
### 3. Using modals
#### 3.1 Basic usage - directly using component
```js
const showModal = async () => {
try {
const res = await NiceModal.show(MyModal, {
title: 'Title',
content: 'Content',
});
console.log('Result:', res);
} catch (error) {
console.log('Cancelled:', error);
}
};
```
#### 3.2 Declarative usage - referencing declared modal via ID
> Can inherit context from declaration
```html
const showModal = async () => {
try {
const res = await NiceModal.show('my-modal', {
title: 'Title',
content: 'Content',
});
console.log('Result:', res);
} catch (error) {
console.log('Cancelled:', error);
}
};
```
#### 3.3 Hook usage - using useModal composition API
```js
const modal = NiceModal.useModal(MyModal);
const showModal = async () => {
try {
const res = await modal.show({
title: 'Title',
content: 'Content',
});
console.log('Result:', res);
} catch (error) {
console.log('Cancelled:', error);
}
};
```
#### 3.4 Registration usage - using ID after registration
```js
// Pre-register modal
NiceModal.register('register-modal', MyModal);
const showModal = async () => {
try {
const res = await NiceModal.show('register-modal', {
title: 'Title',
content: 'Content',
});
console.log('Result:', res);
} catch (error) {
console.log('Cancelled:', error);
}
};
```
## API Reference
### Components
#### `NiceModal.Provider`
Modal container component, needs to wrap the outermost layer of the application.
#### `NiceModal.create(Component)`
Higher-order component for creating modal components.
### Methods
#### `show(modalId, args?)`
Show modal, supports passing parameters.
- `modalId`: Modal ID or component
- `args`: Parameters passed to modal
- Returns: Promise
#### `hide(modalId)`
Hide modal.
- `modalId`: Modal ID or component
- Returns: Promise
#### `remove(modalId)`
Remove modal from DOM.
- `modalId`: Modal ID or component
#### `register(id, component, props?)`
Register modal component.
- `id`: Modal ID
- `component`: Modal component
- `props`: Default props
#### `unregister(id)`
Unregister modal component.
- `id`: Modal ID
### Hook
#### `useModal(modal?, args?)`
Return values:
- `id`: Modal ID
- `args`: Modal parameters
- `visible`: Visibility state
- `show(args?)`: Show modal
- `hide()`: Hide modal
- `remove()`: Remove modal
- `resolve(value)`: Resolve modal Promise
- `reject(reason)`: Reject modal Promise
- `resolveHide(value)`: Resolve hide Promise
## Type Support
This package provides complete TypeScript type declarations, supporting type inference for props and parameters.
## Build Output
- Supports Tree Shaking
- Provides both ESM/CJS formats
```bash
dist/
âââ esm/ # ES Module format
âââ lib/ # CommonJS format
```
## Browser Compatibility
- iOS >= 9
- Android >= 4.4
- Latest two versions of modern browsers
## License
MIT