Van Popup

Vant Popup Component

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

When to Invoke

Invoke this skill when:

• User needs to display a modal or popup
• User wants to create a bottom sheet or slide-out panel
• User needs to show overlay content
• User wants to create a dialog or confirmation box
• User asks about popup positioning or animations

Features

• Multiple Positions: center, top, bottom, left, right
• Round Corners: Built-in rounded corner styles
• Close Icon: Customizable close icon with position options
• Overlay Support: Configurable overlay with custom styles
• Animation: Smooth transition animations
• Teleport: Mount to any DOM element
• Safe Area: Support for iOS safe area adaptation
• Lock Scroll: Prevent background scrolling

API Reference

Props

Events

Slots

Types

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

Usage Examples

Basic Usage

<template>
  <van-cell title="Show Popup" is-link @click="show = true" />
  <van-popup v-model:show="show" :style="{ padding: '64px' }">
    Content
  </van-popup>
</template>

<script setup>
import { ref } from 'vue';

const show = ref(false);
</script>

Position Variants

<template>
  <van-button @click="showTop = true">Top Popup</van-button>
  <van-button @click="showBottom = true">Bottom Popup</van-button>
  <van-button @click="showLeft = true">Left Popup</van-button>
  <van-button @click="showRight = true">Right Popup</van-button>

  <van-popup v-model:show="showTop" position="top" :style="{ height: '30%' }" />
  <van-popup v-model:show="showBottom" position="bottom" :style="{ height: '30%' }" />
  <van-popup v-model:show="showLeft" position="left" :style="{ width: '30%', height: '100%' }" />
  <van-popup v-model:show="showRight" position="right" :style="{ width: '30%', height: '100%' }" />
</template>

<script setup>
import { ref } from 'vue';

const showTop = ref(false);
const showBottom = ref(false);
const showLeft = ref(false);
const showRight = ref(false);
</script>

Close Icon

<template>
  <van-popup
    v-model:show="show"
    closeable
    position="bottom"
    :style="{ height: '30%' }"
  />

  <van-popup
    v-model:show="showCustom"
    closeable
    close-icon="close"
    position="bottom"
    :style="{ height: '30%' }"
  />

  <van-popup
    v-model:show="showPosition"
    closeable
    close-icon-position="top-left"
    position="bottom"
    :style="{ height: '30%' }"
  />
</template>

<script setup>
import { ref } from 'vue';

const show = ref(false);
const showCustom = ref(false);
const showPosition = ref(false);
</script>

Round Corner

<template>
  <van-popup
    v-model:show="showCenter"
    round
    :style="{ padding: '64px' }"
  />

  <van-popup
    v-model:show="showBottom"
    round
    position="bottom"
    :style="{ height: '30%' }"
  />
</template>

<script setup>
import { ref } from 'vue';

const showCenter = ref(false);
const showBottom = ref(false);
</script>

Listen to Events

<template>
  <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"
    @open="onOpen"
    @opened="onOpened"
    @close="onClose"
    @closed="onClosed"
  />
</template>

<script setup>
import { ref } from 'vue';
import { showToast } from 'vant';

const show = ref(false);

const => showToast('click-overlay');
const => showToast('click-close-icon');
const => showToast('open');
const => showToast('opened');
const => showToast('close');
const => showToast('closed');
</script>

Before Close

<template>
  <van-popup
    v-model:show="show"
    position="bottom"
    :style="{ height: '30%' }"
    :before-close="beforeClose"
  >
    <div style="padding: 20px;">
      <p>Are you sure to close?</p>
      <van-button type="primary" @click="confirmClose">Confirm</van-button>
    </div>
  </van-popup>
</template>

<script setup>
import { ref } from 'vue';

const show = ref(false);
let resolveClose = null;

const beforeClose = () => {
  return new Promise((resolve) => {
    resolveClose = resolve;
  });
};

const confirmClose = () => {
  if (resolveClose) {
    resolveClose(true);
    resolveClose = null;
  }
};
</script>

Teleport

<template>
  <van-popup v-model:show="show" teleport="body" />
  <van-popup v-model:show="showApp" teleport="#app" />
</template>

<script setup>
import { ref } from 'vue';

const show = ref(false);
const showApp = ref(false);
</script>

Bottom Sheet with Content

<template>
  <van-cell title="Show Bottom Sheet" is-link @click="show = true" />
  <van-popup
    v-model:show="show"
    position="bottom"
    round
    :style="{ height: '50%' }"
  >
    <div class="sheet-content">
      <h3>Select Option</h3>
      <van-cell-group>
        <van-cell title="Option 1" is-link @click="selectOption(1)" />
        <van-cell title="Option 2" is-link @click="selectOption(2)" />
        <van-cell title="Option 3" is-link @click="selectOption(3)" />
      </van-cell-group>
    </div>
  </van-popup>
</template>

<script setup>
import { ref } from 'vue';

const show = ref(false);

const selectOption = (option) => {
  console.log('Selected:', option);
  show.value = false;
};
</script>

<style scoped>
.sheet-content {
  padding: 16px;
}

.sheet-content h3 {
  margin-bottom: 16px;
  text-align: center;
}
</style>

Best Practices

1. Use appropriate position: Choose position based on content type (bottom for actions, center for alerts)
2. Add round corners: Use round prop for better visual appearance on mobile
3. Handle close events: Implement proper close handling for user actions
4. Use teleport: Mount popup to body for proper z-index stacking
5. Safe area: Enable safe area for bottom popups on iOS devices
6. Lazy render: Keep lazy-render enabled for performance