vant/src/popover

Popover

Intro

Used to display some content on top of another.

Install

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

import { createApp } from 'vue';
import { Popover } from 'vant';

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

Usage

Basic Usage

<van-popover v-model:show="showPopover" :actions="actions" @select="onSelect">
  <template #reference>
    <van-button type="primary">Light Theme</van-button>
  </template>
</van-popover>

import { ref } from 'vue';
import { Toast } from 'vant';

export default {
  setup() {
    const showPopover = ref(false);
    const actions = [
      { text: 'Option 1' },
      { text: 'Option 2' },
      { text: 'Option 3' },
    ];
    const onSelect = (action) => Toast(action.text);

    return {
      actions,
      onSelect,
      showPopover,
    };
  },
};

Dark theme

Using the theme prop to change the style of Popover.

<van-popover v-model:show="showPopover" theme="dark" :actions="actions">
  <template #reference>
    <van-button type="primary">Dark Theme</van-button>
  </template>
</van-popover>

import { ref } from 'vue';

export default {
  setup() {
    const showPopover = ref(false);
    const actions = [
      { text: 'Option 1' },
      { text: 'Option 2' },
      { text: 'Option 3' },
    ];

    return {
      actions,
      showPopover,
    };
  },
};

Placement

<van-popover placement="top" />

placement supports the following values:

top           # Top middle
top-start     # Top left
top-end       # Top right
left          # Left middle
left-start    # Left top
left-end      # Left bottom
right         # Right middle
right-start   # Right top
right-end     # Right bottom
bottom        # Bottom middle
bottom-start  # Bottom left
bottom-end    # Bottom right

Show Icon

<van-popover v-model:show="showPopover" :actions="actions">
  <template #reference>
    <van-button type="primary">Show Icon</van-button>
  </template>
</van-popover>

import { ref } from 'vue';

export default {
  setup() {
    const showPopover = ref(false);
    const actions = [
      { text: 'Option 1', icon: 'add-o' },
      { text: 'Option 2', icon: 'music-o' },
      { text: 'Option 3', icon: 'more-o' },
    ];

    return {
      actions,
      showPopover,
    };
  },
};

Disable Action

Using the disabled option to disable an action.

<van-popover v-model:show="showPopover" :actions="actions">
  <template #reference>
    <van-button type="primary">Disable Action</van-button>
  </template>
</van-popover>

import { ref } from 'vue';

export default {
  setup() {
    const showPopover = ref(false);
    const actions = [
      { text: 'Option 1', disabled: true },
      { text: 'Option 2', disabled: true },
      { text: 'Option 3' },
    ];

    return {
      actions,
      showPopover,
    };
  },
};

Custom Content

<van-popover v-model:show="showPopover">
  <van-grid
    square
    clickable
    :border="false"
    column-num="3"
    style="width: 240px;"
  >
    <van-grid-item
      v-for="i in 6"
      :key="i"
      text="Option"
      icon="photo-o"
      @click="showPopover = false"
    />
  </van-grid>
  <template #reference>
    <van-button type="primary">Custom Content</van-button>
  </template>
</van-popover>

import { ref } from 'vue';

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

API

Props

Attribute	Description	Type	Default
v-model:show	Whether to show Popover	boolean	false
actions	Actions	Action[]	[]
placement	Placement	string	bottom
theme	Theme，can be set to dark	string	light
trigger	Trigger mode，can be set to manual	click
duration	Transition duration, unit second	number | string	0.3
offset	Distance to reference	[number, number]	[0, 8]
overlay	Whether to show overlay	boolean	false
overlay-class v3.0.10	Custom overlay class	string | Array | object	-
overlay-style v3.0.10	Custom overlay style	object	-
close-on-click-action	Whether to close when clicking action	boolean	true
close-on-click-outside	Whether to close when clicking outside	boolean	true
close-on-click-overlay v3.0.10	Whether to close when clicking overlay	boolean	true
teleport	Specifies a target element where Popover will be mounted	string | Element	body
icon-prefix v3.0.17	Icon className prefix	string	van-icon

Data Structure of Action

Key	Description	Type
text	Action Text	string
icon	Icon	string
color	Action Color	string
disabled	Whether to be disabled	boolean
className	className of the option	string | Array | object

Events

Event	Description	Arguments
select	Emitted when an action is clicked	action: Action, index: number
open	Emitted when opening Popover	-
close	Emitted when closing Popover	-
opened	Emitted when Popover is opened	-
closed	Emitted when Popover is closed	-
click-overlay	Emitted when overlay is clicked	event: MouseEvent

Slots

Name	Description
default	Custom content
reference	Reference Element

CSS Variables

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

Name	Default Value	Description
--van-popover-arrow-size	6px	-
--van-popover-border-radius	var(--van-border-radius-lg)	-
--van-popover-action-width	128px	-
--van-popover-action-height	44px	-
--van-popover-action-font-size	var(--van-font-size-md)	-
--van-popover-action-line-height	var(--van-line-height-md)	-
--van-popover-action-icon-size	20px	-
--van-popover-light-text-color	var(--van-text-color)	-
--van-popover-light-background-color	var(--van-white)	-
--van-popover-light-action-disabled-text-color	var(--van-gray-5)	-
--van-popover-dark-text-color	var(--van-white)	-
--van-popover-dark-background-color	#4a4a4a	-
--van-popover-dark-action-disabled-text-color	var(--van-gray-6)	-