Back to Vant

Popup

packages/vant/src/popup/README.md

4.10.07.9 KB
Original Source

Popup

Intro

Used to display pop-up windows, information prompts, etc., and supports multiple pop-up layers to display.

Install

Register component globally via app.use, refer to Component Registration for more registration ways.

js
import { createApp } from 'vue';
import { Popup } from 'vant';

const app = createApp();
app.use(Popup);

Usage

Basic Usage

html
<van-cell title="Show Popup" is-link @click="showPopup" />
<van-popup v-model:show="show" :style="{ padding: '64px' }">Content</van-popup>
js
import { ref } from 'vue';

export default {
  setup() {
    const show = ref(false);
    const showPopup = () => {
      show.value = true;
    };
    return {
      show,
      showPopup,
    };
  },
};

Position

Use position prop to set Popup display position.

The default position is center, it can be set to top, bottom, left, right.

  • When the position is 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.
  • When the position is 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.
html
<!-- 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%' }"
/>

Close Icon

html
<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%' }"
/>

Round Corner

After setting the round prop, the Popup will add different rounded corner styles according to the position.

html
<!-- 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%' }"
/>

Listen To Click Events

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.
html
<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"
/>
js
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,
    };
  },
};

Listen to Display Events

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.
html
<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')"
/>
js
import { ref } from 'vue';
import { showToast } from 'vant';

export default {
  setup() {
    const show = ref(false);
    return {
      show,
      showToast,
    };
  },
};

Get Container

Use teleport prop to specify mount location.

html
<!-- teleport to body -->
<van-popup v-model:show="show" teleport="body" />

<!-- teleport to #app -->
<van-popup v-model:show="show" teleport="#app" />

API

Props

AttributeDescriptionTypeDefault
v-model:showWhether to show popupbooleanfalse
overlayWhether to show overlaybooleantrue
positionCan be set to top bottom right leftstringcenter
overlay-classCustom overlay classstring | Array | object-
overlay-styleCustom overlay styleobject-
overlay-propsOverlay props, see Overlay componentobject-
durationTransition duration, unit secondnumber | string0.3
z-indexSet the z-index to a fixed valuenumber | string2000+
roundWhether to show round cornerbooleanfalse
destroy-on-close v4.9.10Whether to destroy content when closedbooleanfalse
lock-scrollWhether to lock background scrollbooleantrue
lazy-renderWhether to lazy render util appearedbooleantrue
close-on-popstateWhether to close when popstatebooleanfalse
close-on-click-overlayWhether to close when overlay is clickedbooleantrue
closeableWhether to show close iconbooleanfalse
close-iconClose icon namestringcross
close-icon-positionClose Icon Position, can be set to top-left bottom-left bottom-rightstringtop-right
before-closeCallback function before close(action: string) => boolean | Promise<boolean>-
icon-prefixIcon className prefixstringvan-icon
transitionTransition, equivalent to name prop of transitionstring-
transition-appearWhether to apply transition on initial renderbooleanfalse
teleportSpecifies a target element where Popup will be mountedstring | Element-
safe-area-inset-topWhether to enable top safe area adaptationbooleanfalse
safe-area-inset-bottomWhether to enable bottom safe area adaptationbooleanfalse

Events

EventDescriptionArguments
clickEmitted when Popup is clickedevent: MouseEvent
click-overlayEmitted when overlay is clickedevent: MouseEvent
click-close-iconEmitted when close icon is clickedevent: MouseEvent
openEmitted immediately when Popup is opened-
closeEmitted immediately when Popup is closed-
openedEmitted when Popup is opened and the animation ends-
closedEmitted when Popup is closed and the animation ends-

Slots

NameDescription
defaultContent of Popup
overlay-contentContent of Popup overlay

Types

The component exports the following type definitions:

ts
import type {
  PopupProps,
  PopupPosition,
  PopupInstance,
  PopupCloseIconPosition,
} from 'vant';

Theming

CSS Variables

The component provides the following CSS variables, which can be used to customize styles. Please refer to ConfigProvider component.

NameDefault ValueDescription
--van-popup-backgroundvar(--van-background-2)-
--van-popup-transitiontransform var(--van-duration-base)-
--van-popup-round-radius16px-
--van-popup-close-icon-size22px-
--van-popup-close-icon-colorvar(--van-gray-5)-
--van-popup-close-icon-margin16px-
--van-popup-close-icon-z-index1-