Van Popover

Vant Popover Component

Used to display some content on top of another element.

When to Invoke

Invoke this skill when:

• User needs to implement dropdown menus
• User wants to create floating action panels
• User needs to display tooltips or hints
• User wants to show contextual menus
• User asks about popover positioning and themes

Features

• Multiple Themes: Light and dark themes
• Flexible Placement: 12 placement positions
• Action List: Built-in action list support
• Horizontal/Vertical: Action layout direction
• Custom Content: Full content customization via slots
• Controlled/Uncontrolled: Support both modes
• Icon Support: Icons for each action item

API Reference

Props

PopoverAction Structure

Events

Slots

Types

import type {
  PopoverProps,
  PopoverTheme,
  PopoverAction,
  PopoverActionsDirection,
  PopoverTrigger,
  PopoverPlacement,
} from 'vant';

Usage Examples

Basic Usage

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

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

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

const => showToast(action.text);
</script>

Dark Theme

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

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

const showPopover = ref(false);
const actions = [
  { text: 'Option 1' },
  { text: 'Option 2' },
  { text: 'Option 3' },
];
</script>

Horizontal Layout

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

Placement Options

<template>
  <van-popover placement="top" />
</template>

Available placements:

• top, top-start, top-end
• left, left-start, left-end
• right, right-start, right-end
• bottom, bottom-start, bottom-end

With Icons

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

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

const showPopover = ref(false);
const actions = [
  { text: 'Option 1', icon: 'add-o' },
  { text: 'Option 2', icon: 'music-o' },
  { text: 'Option 3', icon: 'more-o' },
];
</script>

Disabled Action

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

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

const showPopover = ref(false);
const actions = [
  { text: 'Option 1', disabled: true },
  { text: 'Option 2', disabled: true },
  { text: 'Option 3' },
];
</script>

Custom Content

<template>
  <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>
</template>

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

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

Uncontrolled Mode

<template>
  <van-popover :actions="actions" placement="top-start" @select="onSelect">
    <template #reference>
      <van-button type="primary">Uncontrolled</van-button>
    </template>
  </van-popover>
</template>

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

const actions = [
  { text: 'Option 1' },
  { text: 'Option 2' },
  { text: 'Option 3' },
];

const => showToast(action.text);
</script>

Common Issues

1. Popover Not Showing

Ensure v-model:show is properly bound:

<van-popover v-model:show="showPopover">
  <template #reference>
    <van-button @click="showPopover = true">Show</van-button>
  </template>
</van-popover>

2. Manual Trigger

Use trigger="manual" for programmatic control:

<van-popover v-model:show="show" trigger="manual">
  <template #reference>
    <van-button>Reference</van-button>
  </template>
</van-popover>

3. Preventing Close

Set close-on-click-action to false:

<van-popover
  v-model:show="show"
  :actions="actions"
  :close-on-click-action="false"
/>

Component Interactions

With Navigation Bar

<template>
  <van-nav-bar title="Title">
    <template #right>
      <van-popover :actions="actions" @select="onSelect">
        <template #reference>
          <van-icon name="ellipsis" size="20" />
        </template>
      </van-popover>
    </template>
  </van-nav-bar>
</template>

With Context Menu

<template>
  <div @contextmenu.prevent="showMenu">
    Right click here
    <van-popover
      v-model:show="showPopover"
      :actions="actions"
      placement="bottom-start"
    >
      <template #reference>
        <div style="position: absolute;"></div>
      </template>
    </van-popover>
  </div>
</template>

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

const showPopover = ref(false);
const actions = [
  { text: 'Copy' },
  { text: 'Paste' },
  { text: 'Delete' },
];

const showMenu = () => {
  showPopover.value = true;
};
</script>

Best Practices

1. Use appropriate placement: Choose placement based on available space
2. Limit actions: Keep action list concise for better UX
3. Provide visual feedback: Use icons and colors for better recognition
4. Consider mobile: Ensure popover is accessible on touch devices
5. Test positioning: Verify popover positions correctly in different scenarios