packages/vant/src/popup/README.md
Used to display pop-up windows, information prompts, etc., and supports multiple pop-up layers to display.
Register component globally via app.use, refer to Component Registration for more registration ways.
import { createApp } from 'vue';
import { Popup } from 'vant';
const app = createApp();
app.use(Popup);
<van-cell title="Show Popup" is-link @click="showPopup" />
<van-popup v-model:show="show" :style="{ padding: '64px' }">Content</van-popup>
import { ref } from 'vue';
export default {
setup() {
const show = ref(false);
const showPopup = () => {
show.value = true;
};
return {
show,
showPopup,
};
},
};
Use position prop to set Popup display position.
The default position is center, it can be set to top, bottom, left, right.
top or bottom, the default width is consistent with the screen width, and the height of the Popup depends on the height of the content.left or right side, the width and height are not set by default, and the width and height of the popup depend on the width and height of the content.<!-- top popup -->
<van-popup v-model:show="showTop" position="top" :style="{ height: '30%' }" />
<!-- bottom popup -->
<van-popup
v-model:show="showBottom"
position="bottom"
:style="{ height: '30%' }"
/>
<!-- left popup -->
<van-popup
v-model:show="showLeft"
position="left"
:style="{ width: '30%', height: '100%' }"
/>
<!-- Popup on the right -->
<van-popup
v-model:show="showRight"
position="right"
:style="{ width: '30%', height: '100%' }"
/>
<van-popup
v-model:show="show"
closeable
position="bottom"
:style="{ height: '30%' }"
/>
<!-- Custom Icon -->
<van-popup
v-model:show="show"
closeable
close-icon="close"
position="bottom"
:style="{ height: '30%' }"
/>
<!-- Icon Position -->
<van-popup
v-model:show="show"
closeable
close-icon-position="top-left"
position="bottom"
:style="{ height: '30%' }"
/>
After setting the round prop, the Popup will add different rounded corner styles according to the position.
<!-- Round Popup (center) -->
<van-popup v-model:show="showCenter" round :style="{ padding: '64px' }" />
<!-- Round Popup (bottom) -->
<van-popup
v-model:show="showBottom"
round
position="bottom"
:style="{ height: '30%' }"
/>
Popup supports following events:
click: Emitted when Popup is clicked.click-overlay: Emitted when overlay is clicked.click-close-icon: Emitted when close icon is clicked.<van-cell title="Listen Click Events" is-link @click="show = true" />
<van-popup
v-model:show="show"
position="bottom"
:style="{ height: '30%' }"
closeable
@click-overlay="onClickOverlay"
@click-close-icon="onClickCloseIcon"
/>
import { ref } from 'vue';
import { showToast } from 'vant';
export default {
setup() {
const show = ref(false);
const onClickOverlay = () => {
showToast('click-overlay');
};
const onClickCloseIcon = () => {
showToast('click-close-icon');
};
return {
show,
onClickOverlay,
onClickCloseIcon,
};
},
};
When the Popup is opened or closed, the following events will be emitted:
open: Emitted immediately when the Popup is opened.opened: Emitted when the Popup is opened and the animation ends.close: Emitted immediately when the Popup is closed.closed: Emitted when the Popup is closed and the animation ends.<van-cell title="Listen to display events" is-link @click="show = true" />
<van-popup
v-model:show="show"
position="bottom"
:style="{ height: '30%' }"
@open="showToast('open')"
@opened="showToast('opened')"
@close="showToast('close')"
@closed="showToast('closed')"
/>
import { ref } from 'vue';
import { showToast } from 'vant';
export default {
setup() {
const show = ref(false);
return {
show,
showToast,
};
},
};
Use teleport prop to specify mount location.
<!-- teleport to body -->
<van-popup v-model:show="show" teleport="body" />
<!-- teleport to #app -->
<van-popup v-model:show="show" teleport="#app" />
| Attribute | Description | Type | Default |
|---|---|---|---|
| v-model:show | Whether to show popup | boolean | false |
| overlay | Whether to show overlay | boolean | true |
| position | Can be set to top bottom right left | string | center |
| overlay-class | Custom overlay class | string | Array | object | - |
| overlay-style | Custom overlay style | object | - |
| overlay-props | Overlay props, see Overlay component | object | - |
| duration | Transition duration, unit second | number | string | 0.3 |
| z-index | Set the z-index to a fixed value | number | string | 2000+ |
| round | Whether to show round corner | boolean | false |
destroy-on-close v4.9.10 | Whether to destroy content when closed | boolean | false |
| lock-scroll | Whether to lock background scroll | boolean | true |
| lazy-render | Whether to lazy render util appeared | boolean | true |
| close-on-popstate | Whether to close when popstate | boolean | false |
| close-on-click-overlay | Whether to close when overlay is clicked | boolean | true |
| closeable | Whether to show close icon | boolean | false |
| close-icon | Close icon name | string | cross |
| close-icon-position | Close Icon Position, can be set to top-left bottom-left bottom-right | string | top-right |
| before-close | Callback function before close | (action: string) => boolean | Promise<boolean> | - |
| icon-prefix | Icon className prefix | string | van-icon |
| transition | Transition, equivalent to name prop of transition | string | - |
| transition-appear | Whether to apply transition on initial render | boolean | false |
| teleport | Specifies a target element where Popup will be mounted | string | Element | - |
| safe-area-inset-top | Whether to enable top safe area adaptation | boolean | false |
| safe-area-inset-bottom | Whether to enable bottom safe area adaptation | boolean | false |
| Event | Description | Arguments |
|---|---|---|
| click | Emitted when Popup is clicked | event: MouseEvent |
| click-overlay | Emitted when overlay is clicked | event: MouseEvent |
| click-close-icon | Emitted when close icon is clicked | event: MouseEvent |
| open | Emitted immediately when Popup is opened | - |
| close | Emitted immediately when Popup is closed | - |
| opened | Emitted when Popup is opened and the animation ends | - |
| closed | Emitted when Popup is closed and the animation ends | - |
| Name | Description |
|---|---|
| default | Content of Popup |
| overlay-content | Content of Popup overlay |
The component exports the following type definitions:
import type {
PopupProps,
PopupPosition,
PopupInstance,
PopupCloseIconPosition,
} from 'vant';
The component provides the following CSS variables, which can be used to customize styles. Please refer to ConfigProvider component.
| Name | Default Value | Description |
|---|---|---|
| --van-popup-background | var(--van-background-2) | - |
| --van-popup-transition | transform var(--van-duration-base) | - |
| --van-popup-round-radius | 16px | - |
| --van-popup-close-icon-size | 22px | - |
| --van-popup-close-icon-color | var(--van-gray-5) | - |
| --van-popup-close-icon-margin | 16px | - |
| --van-popup-close-icon-z-index | 1 | - |