Vant Vue3

Vant of Vue 3

When to use this skill

Use this skill whenever the user is working with Vant for Vue 3 or asks for:

• Vant installation, setup, or project initialization
• Vue 3 mobile UI implementation with vant
• van-button, van-cell, van-form, van-dialog, van-popup, van-toast
• Vant ConfigProvider, theme variables, or theme customization
• Mobile-first page structure, touch-oriented UI, or form flows based on Vant
• Converting generic Vue 3 UI to Vant component usage
• Reviewing or fixing existing Vant Vue 3 code

Trigger terms include:

• vant
• vant vue3
• Vant of Vue 3.0
• van-button, van-form, van-cell, van-dialog, van-toast, van-popup
• ConfigProvider
• theme-vars
• vant 组件
• Vant 主题定制

Scope and alignment

This skill is aligned to the official Vant documentation entry points:

• Official website: https://vant-ui.github.io/
• Official guide: https://vant-ui.github.io/vant/#/zh-CN

The local skill content only claims coverage for files that actually exist in this skill directory. Do not reference non-existent local files. If the requested Vant component is not covered by a local example file, use the official guide as the primary reference and reuse the closest local pattern.

For the exact local-to-official mapping, read:

• references/official-mapping.md

How to use this skill

Step 1: Identify the request area

Map the user request to one of these areas:

1. Quick start / setup

• Installing Vant
• Importing styles
• Full import vs on-demand import
• Vue 3 project bootstrap

2. Component implementation

• Button
• Cell
• Form
• Dialog
• Toast
• Popup

3. Global config and theming

• ConfigProvider
• theme-vars
• Theme customization

4. API lookup

• Common props
• Component props/events/methods
• Global config API

5. Template or scaffold

• Project setup template
• Reusable component structure

Step 2: Load only the matching files

Use the smallest relevant set of files.

A. Quick start / setup

• examples/getting-started/installation.md
• examples/getting-started/basic-usage.md
• templates/project-setup.md

Use these when the user asks how to install Vant, register components, import CSS, or start a Vue 3 + Vant project.

B. Covered component examples

Use only the component file that matches the user request:

• Button → examples/components/button.md
• Cell → examples/components/cell.md
• Form → examples/components/form.md
• Dialog → examples/components/dialog.md
• Popup → examples/components/popup.md
• Toast → examples/components/toast.md

C. Global config and theme

• api/config-provider.md
• examples/advanced/theme-customization.md

Use these for ConfigProvider, dark/light theme handling, theme-vars, CSS variables, or global UI behavior.

D. API lookup

• api/components.md
• api/config-provider.md

Use these when the user needs prop names, event names, method names, or a quick API summary.

E. Official navigation and coverage boundaries

• references/official-mapping.md

Use this file when:

• You need to confirm what this skill covers locally
• You need to route the user from an official Vant section to a local file
• You need to handle a Vant component that is not yet covered by a local example

Step 3: Follow the response workflow

When answering with this skill:

1. Confirm the target is Vant for Vue 3, not another Vue UI library. 2. Pick the matching local example or API file. 3. Keep code examples in Vue 3 Composition API style. 4. Preserve Vant naming and usage conventions:

• import from vant
• use van- components in templates
• import vant/lib/index.css where setup requires it

5. Prefer mobile-first structure and touch-oriented interaction patterns. 6. If the requested component is not covered locally:

• say that the local skill does not contain a dedicated example file for that component
• route via references/official-mapping.md
• use the official guide as the primary source of truth
• adapt the closest covered local example style instead of inventing fake local files

Local navigation map

This is the actual local navigation surface for the skill.

Getting started

• examples/getting-started/installation.md
• examples/getting-started/basic-usage.md
• templates/project-setup.md

Components covered locally

• examples/components/button.md
• examples/components/cell.md
• examples/components/form.md
• examples/components/dialog.md
• examples/components/popup.md
• examples/components/toast.md

Theme and global configuration

• api/config-provider.md
• examples/advanced/theme-customization.md

API summaries

• api/components.md
• api/config-provider.md

Official mapping

• references/official-mapping.md

Working rules

Do

• Use only local files that actually exist
• Keep answers anchored to the official Vant guide structure
• Prefer concrete component code over abstract explanation
• Use script setup style for Vue 3 examples unless the user already uses another style
• Mention ConfigProvider when the user asks about global theme or locale-like app-wide config
• Keep code samples runnable and focused

Do not

• Do not reference icon.md, tabs.md, navbar.md, or other files that do not exist in this skill
• Do not pretend this skill has full local coverage for every Vant component
• Do not mix Vant patterns with Element Plus, Ant Design Vue, or other UI libraries
• Do not output generic Vue UI advice when the user explicitly asks for Vant

Answer patterns

If the user asks for setup

Load:

• examples/getting-started/installation.md
• templates/project-setup.md

Return:

• install command
• CSS import
• registration strategy
• minimal Vue 3 + Vant starter

If the user asks for a covered component

Load:

• the matching file under examples/components/
• api/components.md if props/events are involved

Return:

• minimal example first
• then props/events/method notes
• then usage pitfalls if relevant

If the user asks for theme customization

Load:

• api/config-provider.md
• examples/advanced/theme-customization.md

Return:

• ConfigProvider usage
• theme-vars example
• CSS variable strategy
• scope and inheritance notes

If the user asks for an uncovered Vant component

Load:

• references/official-mapping.md
• nearest covered local file

Return:

• explicit note that the local skill has no dedicated example file for that component
• route to the official Vant guide section
• provide a Vant-consistent example following the same conventions used in this skill

Quality checklist

Before responding, verify that:

• the answer is specifically for Vant of Vue 3
• all referenced local files exist
• imports come from vant
• examples use Vue 3 syntax
• setup examples include CSS import where needed
• theme answers use ConfigProvider / theme-vars consistently

Resources

• Official website: https://vant-ui.github.io/
• Official guide: https://vant-ui.github.io/vant/#/zh-CN
• Local official mapping: references/official-mapping.md

Keywords

Vant, Vant Vue 3, Vant of Vue 3.0, Vue 3 mobile UI, van-button, van-cell, van-form, van-dialog, van-toast, van-popup, ConfigProvider, theme-vars, mobile-first UI, Vant theme, Vant setup, Vant component library, vant 组件, vant vue3, 移动端组件库, 按钮, 单元格, 表单, 对话框, 提示, 弹出层, 主题定制

能力边界

✅ 适用场景

• 当你需要使用此技能对应的技术栈时
• 当项目需要遵循最佳实践时
• 当需要快速上手或深入理解核心概念时

⚠️ 需要注意

• 复杂业务逻辑需要结合具体场景调整
• 性能优化需要根据实际数据量评估

❌ 不适用场景

• 不相关的技术栈或框架
• 需要完全自定义的特殊场景

常见陷阱 (Gotchas)

1. 版本兼容性：注意框架版本与依赖库的兼容性，不同版本 API 可能有差异 2. 配置文件格式：配置文件格式错误是最常见的问题，建议使用编辑器的语法检查 3. 环境变量：确保所有必要的环境变量已正确设置，敏感信息不要硬编码 4. 依赖冲突：多版本共存时注意依赖冲突，使用 lock 文件锁定版本 5. 性能陷阱：大数据量场景下注意性能优化，避免 N+1 查询等常见问题

Components API | 组件 API

适用范围：本文件只总结当前本地 skill 已覆盖的组件与能力，不声称覆盖全部 Vant 组件。

当前本地覆盖组件：

• Button
• Cell
• Form / Field
• Dialog
• Toast
• Popup

关联示例文件：

• Button → examples/components/button.md
• Cell → examples/components/cell.md
• Form → examples/components/form.md
• Dialog → examples/components/dialog.md
• Toast → examples/components/toast.md
• Popup → examples/components/popup.md

Common usage rules

• 所有组件示例默认使用 Vue 3 script setup
• 所有组件从 vant 导入
• 交互型组件优先保持移动端使用场景
• 需要主题配置时，配合 api/config-provider.md

Button API summary

Use when:

• 需要操作按钮
• 需要提交、确认、触发事件入口

Common props:

• type: primary / success / warning / danger / default
• size: large / normal / small / mini
• shape: square / round
• plain: plain style
• disabled: disabled state
• loading: loading state
• icon: icon name

Common events:

• @click

See also:

• examples/components/button.md

Cell API summary

Use when:

• 需要列表项、信息项、跳转入口

Common props:

• title
• value
• label
• icon
• is-link
• arrow-direction

Common events:

• @click

Related components:

• CellGroup

See also:

• examples/components/cell.md

Form API summary

Use when:

• 需要登录、注册、资料编辑、校验提交

Core components:

• Form
• Field
• CellGroup
• Button

Common events:

• @submit
• @failed

Common methods:

• validate()
• resetValidation()

Common field props:

• v-model
• name
• label
• placeholder
• :rules
• type
• disabled

See also:

• examples/components/form.md

Dialog API summary

Use when:

• 需要确认、警告、阻断式提示、带表单输入的弹窗

Component props:

• v-model:show
• title
• message
• show-cancel-button
• confirm-button-text
• cancel-button-text

Component events:

• @confirm
• @cancel

Programmatic APIs:

• showDialog(options)
• showConfirmDialog(options)

See also:

• examples/components/dialog.md

Toast API summary

Use when:

• 需要轻提示、成功提示、失败提示、加载提示

Programmatic APIs:

• showToast(message | options)
• showSuccessToast(message)
• showFailToast(message)
• showLoadingToast(message)

Common options:

• type
• message
• duration
• position

Component usage:

• van-toast with v-model:show

See also:

• examples/components/toast.md

Popup API summary

Use when:

• 需要底部弹层、侧边滑出层、中间弹层、可关闭容器

Common props:

• v-model:show
• position
• round
• closeable
• close-icon-position
• overlay

Common events:

• @close

See also:

• examples/components/popup.md

Selection guide

• If the user asks for a primary action control, start with Button
• If the user asks for list-style navigation or info rows, start with Cell
• If the user asks for data entry or validation, start with Form
• If the user asks for confirmation or interruption, start with Dialog
• If the user asks for lightweight feedback, start with Toast
• If the user asks for overlay content or slide-up panels, start with Popup

ConfigProvider API | ConfigProvider API

官方文档入口: https://vant-ui.github.io/vant/#/zh-CN 官方对应章节: ConfigProvider

API Reference

ConfigProvider component API for global configuration.

ConfigProvider

Provides global configuration for Vant components.

Props:

• theme: Theme configuration (light, dark)
• theme-vars: Custom theme variables
• tag: Root element tag
• z-index: Z-index for popup components

Example: Basic Usage

<template>
  <van-config-provider :theme-vars="themeVars">
    <App />
  </van-config-provider>
</template>

<script setup>
import { ConfigProvider as VanConfigProvider } from 'vant'

const themeVars = {
  primaryColor: '#07c160',
  successColor: '#07c160',
  dangerColor: '#ee0a24'
}
</script>

Example: Theme Variables

<template>
  <van-config-provider :theme-vars="themeVars">
    <van-button type="primary">Button</van-button>
  </van-config-provider>
</template>

<script setup>
import { ConfigProvider as VanConfigProvider, Button as VanButton } from 'vant'

const themeVars = {
  buttonPrimaryBackground: '#07c160',
  buttonPrimaryBorderColor: '#07c160'
}
</script>

Key Points

• Wrap app with ConfigProvider for global config
• Use theme-vars prop for theme customization
• Use theme prop for light/dark theme
• ConfigProvider affects all child components
• Can nest ConfigProviders for different scopes
• Theme variables use CSS variables

Theme Customization | 主题定制

官方文档入口: https://vant-ui.github.io/vant/#/zh-CN 官方对应章节: ConfigProvider / 主题定制

Instructions

This example demonstrates how to customize Vant theme.

Key Concepts

• Using ConfigProvider
• Customizing theme variables
• CSS variables
• Theme switching

Example: Basic Theme Customization

<template>
  <van-config-provider :theme-vars="themeVars">
    <van-button type="primary">Primary Button</van-button>
  </van-config-provider>
</template>

<script setup>
import { ConfigProvider as VanConfigProvider, Button as VanButton } from 'vant'

const themeVars = {
  primaryColor: '#07c160',
  successColor: '#07c160',
  dangerColor: '#ee0a24'
}
</script>

Example: Customizing Multiple Variables

<template>
  <van-config-provider :theme-vars="themeVars">
    <van-button type="primary">Button</van-button>
    <van-cell title="Cell" />
  </van-config-provider>
</template>

<script setup>
import { ConfigProvider as VanConfigProvider, Button as VanButton, Cell as VanCell } from 'vant'

const themeVars = {
  buttonPrimaryBackground: '#07c160',
  buttonPrimaryBorderColor: '#07c160',
  cellFontSize: '16px',
  cellTextColor: '#323233'
}
</script>

Example: Using CSS Variables

<template>
  <van-config-provider :theme-vars="themeVars">
    <App />
  </van-config-provider>
</template>

<script setup>
import { ConfigProvider as VanConfigProvider } from 'vant'

const themeVars = {
  primaryColor: 'var(--my-primary-color)',
  successColor: 'var(--my-success-color)'
}
</script>

<style>
:root {
  --my-primary-color: #07c160;
  --my-success-color: #07c160;
}
</style>

Key Points

• Use ConfigProvider with theme-vars prop
• Customize theme variables via theme-vars property
• Theme changes apply to all child components
• Supports CSS variables
• Can switch themes dynamically
• Theme variables follow Vant naming convention

Related local files

• Config API: api/config-provider.md
• Project scaffold: templates/project-setup.md

Button | 按钮

官方文档入口: https://vant-ui.github.io/vant/#/zh-CN 官方对应章节: Button / 按钮

Instructions

This example demonstrates how to use the Button component in Vant.

Key Concepts

• Button types (primary, success, warning, danger)
• Button sizes (large, normal, small, mini)
• Button shapes (square, round)
• Button states (disabled, loading)
• Button with icons
• Button groups

Example: Button Types

<template>
  <van-button type="primary">Primary</van-button>
  <van-button type="success">Success</van-button>
  <van-button type="warning">Warning</van-button>
  <van-button type="danger">Danger</van-button>
  <van-button type="default">Default</van-button>
</template>

<script setup>
import { Button as VanButton } from 'vant'
</script>

Example: Button Sizes

<template>
  <van-button type="primary" size="large">Large</van-button>
  <van-button type="primary" size="normal">Normal</van-button>
  <van-button type="primary" size="small">Small</van-button>
  <van-button type="primary" size="mini">Mini</van-button>
</template>

<script setup>
import { Button as VanButton } from 'vant'
</script>

Example: Button with Icon

<template>
  <van-button type="primary" icon="plus">Add</van-button>
  <van-button type="primary" icon="search">Search</van-button>
</template>

<script setup>
import { Button as VanButton } from 'vant'
</script>

Example: Loading State

<template>
  <van-button
    type="primary"
    :loading="loading"
    loading-text="Loading..."
    @click="handleClick"
  >
    Click Me
  </van-button>
</template>

<script setup>
import { ref } from 'vue'
import { Button as VanButton } from 'vant'

const loading = ref(false)

const handleClick = () => {
  loading.value = true
  setTimeout(() => {
    loading.value = false
  }, 2000)
}
</script>

Example: Disabled Button

<template>
  <van-button type="primary" disabled>Disabled</van-button>
  <van-button :disabled="disabled">Toggle Disabled</van-button>
</template>

<script setup>
import { ref } from 'vue'
import { Button as VanButton } from 'vant'

const disabled = ref(false)
</script>

Example: Button Group

<template>
  <van-button-group>
    <van-button type="primary">Left</van-button>
    <van-button type="primary">Middle</van-button>
    <van-button type="primary">Right</van-button>
  </van-button-group>
</template>

<script setup>
import { Button as VanButton, ButtonGroup as VanButtonGroup } from 'vant'
</script>

Key Points

• Use type prop for button style (primary, success, warning, danger, default)
• Use size prop for button size (large, normal, small, mini)
• Use icon prop for icon buttons
• Use loading prop for loading state
• Use disabled prop to disable button
• Use van-button-group for button groups
• Button supports all standard HTML button attributes

Related local files

• API summary: api/components.md
• Form submit button pattern: examples/components/form.md

Cell | 单元格

官方文档入口: https://vant-ui.github.io/vant/#/zh-CN 官方对应章节: Cell / 单元格

Instructions

This example demonstrates how to use the Cell component in Vant.

Key Concepts

• Basic Cell
• Cell with value
• Cell with icon
• Cell with arrow
• Cell with click handler
• Cell groups

Example: Basic Cell

<template>
  <van-cell title="Cell Title" />
  <van-cell title="Cell Title" value="Content" />
</template>

<script setup>
import { Cell as VanCell } from 'vant'
</script>

Example: Cell with Icon

<template>
  <van-cell
    title="Cell Title"
    value="Content"
    icon="location-o"
  />
</template>

<script setup>
import { Cell as VanCell } from 'vant'
</script>

Example: Cell with Arrow

<template>
  <van-cell title="Cell Title" is-link />
  <van-cell title="Cell Title" is-link arrow-direction="down" />
</template>

<script setup>
import { Cell as VanCell } from 'vant'
</script>

Example: Cell with Click Handler

<template>
  <van-cell
    title="Cell Title"
    value="Content"
    is-link
    @click="handleClick"
  />
</template>

<script setup>
import { Cell as VanCell, showToast } from 'vant'

const handleClick = () => {
  showToast('Cell clicked')
}
</script>

Example: Cell Groups

<template>
  <van-cell-group>
    <van-cell title="Cell 1" value="Content 1" />
    <van-cell title="Cell 2" value="Content 2" />
    <van-cell title="Cell 3" value="Content 3" />
  </van-cell-group>
</template>

<script setup>
import { Cell as VanCell, CellGroup as VanCellGroup } from 'vant'
</script>

Key Points

• Use van-cell component for cell display
• Use title prop for cell title
• Use value prop for cell value
• Use icon prop for cell icon
• Use is-link prop for arrow indicator
• Use @click for click handlers
• Use van-cell-group to group cells

Related local files

• API summary: api/components.md
• Nearby component pattern: examples/components/button.md

Dialog | 对话框

官方文档入口: https://vant-ui.github.io/vant/#/zh-CN 官方对应章节: Dialog / 弹出框

Instructions

This example demonstrates how to use the Dialog component in Vant.

Key Concepts

• Basic Dialog
• Dialog with confirm
• Dialog with alert
• Dialog with custom content
• Dialog methods

Example: Basic Dialog

<template>
  <van-button @click="show = true">Show Dialog</van-button>
  <van-dialog
    v-model:show="show"
    title="Title"
    message="This is a dialog message"
  />
</template>

<script setup>
import { ref } from 'vue'
import { Button as VanButton, Dialog as VanDialog } from 'vant'

const show = ref(false)
</script>

Example: Dialog with Confirm

<template>
  <van-button @click="showConfirm">Show Confirm</van-button>
</template>

<script setup>
import { Button as VanButton, showConfirmDialog } from 'vant'

const showConfirm = () => {
  showConfirmDialog({
    title: 'Confirm',
    message: 'Are you sure?'
  })
    .then(() => {
      console.log('Confirmed')
    })
    .catch(() => {
      console.log('Cancelled')
    })
}
</script>

Example: Dialog with Alert

<template>
  <van-button @click="showAlert">Show Alert</van-button>
</template>

<script setup>
import { Button as VanButton, showDialog } from 'vant'

const showAlert = () => {
  showDialog({
    title: 'Alert',
    message: 'This is an alert'
  })
}
</script>

Example: Dialog with Custom Content

<template>
  <van-button @click="show = true">Show Custom Dialog</van-button>
  <van-dialog
    v-model:show="show"
    title="Custom Dialog"
    show-cancel-button
    @confirm="handleConfirm"
    @cancel="show = false"
  >
    <van-field v-model="value" placeholder="Enter text" />
  </van-dialog>
</template>

<script setup>
import { ref } from 'vue'
import { Button as VanButton, Dialog as VanDialog, Field as VanField, showToast } from 'vant'

const show = ref(false)
const value = ref('')

const handleConfirm = () => {
  showToast(value.value)
  show.value = false
}
</script>

Key Points

• Use van-dialog component for dialog display
• Use v-model:show for dialog visibility
• Use title prop for dialog title
• Use message prop for dialog message
• Use showConfirmDialog() for confirm dialogs
• Use showDialog() for alert dialogs
• Use @confirm and @cancel for button handlers

Related local files

• API summary: api/components.md
• Feedback pattern: examples/components/toast.md
• Form-in-dialog pattern: examples/components/form.md

Form | 表单

官方文档入口: https://vant-ui.github.io/vant/#/zh-CN 官方对应章节: Form / 表单

Instructions

This example demonstrates how to use Form components in Vant.

Key Concepts

• Form component setup
• Form validation
• Form fields
• Form submission
• Form layout

Example: Basic Form

<template>
  <van-form @submit="onSubmit">
    <van-cell-group inset>
      <van-field
        v-model="form.username"
        name="username"
        label="Username"
        placeholder="Username"
        :rules="[{ required: true, message: 'Please enter username' }]"
      />
      <van-field
        v-model="form.password"
        type="password"
        name="password"
        label="Password"
        placeholder="Password"
        :rules="[{ required: true, message: 'Please enter password' }]"
      />
    </van-cell-group>
    <div style="margin: 16px;">
      <van-button round block type="primary" native-type="submit">
        Submit
      </van-button>
    </div>
  </van-form>
</template>

<script setup>
import { ref } from 'vue'
import { Form as VanForm, Field as VanField, CellGroup as VanCellGroup, Button as VanButton } from 'vant'

const form = ref({
  username: '',
  password: ''
})

const onSubmit = (values) => {
  console.log('Submit:', values)
}
</script>

Example: Form with Validation

<template>
  <van-form @submit="onSubmit" @failed="onFailed">
    <van-cell-group inset>
      <van-field
        v-model="form.email"
        name="email"
        label="Email"
        placeholder="Email"
        :rules="emailRules"
      />
      <van-field
        v-model="form.password"
        type="password"
        name="password"
        label="Password"
        placeholder="Password"
        :rules="passwordRules"
      />
    </van-cell-group>
    <div style="margin: 16px;">
      <van-button round block type="primary" native-type="submit">
        Submit
      </van-button>
    </div>
  </van-form>
</template>

<script setup>
import { ref } from 'vue'
import { Form as VanForm, Field as VanField, CellGroup as VanCellGroup, Button as VanButton } from 'vant'

const form = ref({
  email: '',
  password: ''
})

const emailRules = [
  { required: true, message: 'Please enter email' },
  { pattern: /^[A-Za-z0-9\u4e00-\u9fa5]+@[a-zA-Z0-9_-]+(\.[a-zA-Z0-9_-]+)+$/, message: 'Invalid email' }
]

const passwordRules = [
  { required: true, message: 'Please enter password' },
  { min: 6, message: 'Password must be at least 6 characters' }
]

const onSubmit = (values) => {
  console.log('Submit:', values)
}

const onFailed = (errorInfo) => {
  console.log('Failed:', errorInfo)
}
</script>

Example: Form with Ref

<template>
  <van-form ref="formRef">
    <van-cell-group inset>
      <van-field
        v-model="form.username"
        name="username"
        label="Username"
        :rules="[{ required: true, message: 'Please enter username' }]"
      />
    </van-cell-group>
    <div style="margin: 16px;">
      <van-button type="primary" @click="submit">Submit</van-button>
      <van-button @click="reset">Reset</van-button>
    </div>
  </van-form>
</template>

<script setup>
import { ref } from 'vue'
import { Form as VanForm, Field as VanField, CellGroup as VanCellGroup, Button as VanButton } from 'vant'

const formRef = ref(null)
const form = ref({
  username: ''
})

const submit = async () => {
  try {
    await formRef.value.validate()
    console.log('Form valid:', form.value)
  } catch (error) {
    console.log('Validation failed')
  }
}

const reset = () => {
  formRef.value.resetValidation()
  form.value.username = ''
}
</script>

Key Points

• Use van-form component to wrap form fields
• Use van-field for form inputs
• Use :rules prop for validation rules
• Use @submit for form submission
• Use @failed for validation failure
• Use ref and validate() method for programmatic validation
• Use native-type="submit" for submit button

Related local files

• API summary: api/components.md
• Popup with form pattern: examples/components/popup.md
• Dialog with input pattern: examples/components/dialog.md

Popup | 弹出层

官方文档入口: https://vant-ui.github.io/vant/#/zh-CN 官方对应章节: Popup / 弹出层

Instructions

This example demonstrates how to use the Popup component in Vant.

Key Concepts

• Basic Popup
• Popup positions (top, bottom, left, right, center)
• Popup with close button
• Popup with round corners
• Popup with overlay

Example: Basic Popup

<template>
  <van-button @click="show = true">Show Popup</van-button>
  <van-popup v-model:show="show" position="bottom">
    <div style="padding: 20px;">Popup content</div>
  </van-popup>
</template>

<script setup>
import { ref } from 'vue'
import { Button as VanButton, Popup as VanPopup } from 'vant'

const show = ref(false)
</script>

Example: Popup Positions

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

  <van-popup v-model:show="showTop" position="top">
    <div style="padding: 20px;">Top popup</div>
  </van-popup>
  <van-popup v-model:show="showBottom" position="bottom">
    <div style="padding: 20px;">Bottom popup</div>
  </van-popup>
  <van-popup v-model:show="showLeft" position="left">
    <div style="padding: 20px;">Left popup</div>
  </van-popup>
  <van-popup v-model:show="showRight" position="right">
    <div style="padding: 20px;">Right popup</div>
  </van-popup>
  <van-popup v-model:show="showCenter" position="center">
    <div style="padding: 20px;">Center popup</div>
  </van-popup>
</template>

<script setup>
import { ref } from 'vue'
import { Button as VanButton, Popup as VanPopup } from 'vant'

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

Example: Popup with Round Corners

<template>
  <van-button @click="show = true">Show Popup</van-button>
  <van-popup
    v-model:show="show"
    position="bottom"
    round
  >
    <div style="padding: 20px;">Popup with round corners</div>
  </van-popup>
</template>

<script setup>
import { ref } from 'vue'
import { Button as VanButton, Popup as VanPopup } from 'vant'

const show = ref(false)
</script>

Example: Popup with Close Button

<template>
  <van-button @click="show = true">Show Popup</van-button>
  <van-popup
    v-model:show="show"
    position="bottom"
    closeable
    close-icon-position="top-right"
  >
    <div style="padding: 20px;">Popup with close button</div>
  </van-popup>
</template>

<script setup>
import { ref } from 'vue'
import { Button as VanButton, Popup as VanPopup } from 'vant'

const show = ref(false)
</script>

Key Points

• Use van-popup component for popup display
• Use v-model:show for popup visibility
• Use position prop for popup position (top, bottom, left, right, center)
• Use round prop for round corners
• Use closeable prop for close button
• Use close-icon-position for close button position
• Popup supports overlay and click-to-close

Related local files

• API summary: api/components.md
• Dialog comparison: examples/components/dialog.md

Toast | 提示

官方文档入口: https://vant-ui.github.io/vant/#/zh-CN 官方对应章节: Toast / 轻提示

Instructions

This example demonstrates how to use the Toast component in Vant.

Key Concepts

• Basic toast
• Toast types (success, fail, loading)
• Toast with custom message
• Toast duration
• Toast position

Example: Basic Toast

<template>
  <van-button @click="showToast">Show Toast</van-button>
</template>

<script setup>
import { Button as VanButton, showToast } from 'vant'

const showToast = () => {
  showToast('This is a toast message')
}
</script>

Example: Toast Types

<template>
  <van-button @click="showSuccess">Success</van-button>
  <van-button @click="showFail">Fail</van-button>
  <van-button @click="showLoading">Loading</van-button>
</template>

<script setup>
import { Button as VanButton, showToast, showSuccessToast, showFailToast, showLoadingToast } from 'vant'

const showSuccess = () => {
  showSuccessToast('Success message')
}

const showFail = () => {
  showFailToast('Fail message')
}

const showLoading = () => {
  showLoadingToast('Loading...')
}
</script>

Example: Toast with Options

<template>
  <van-button @click="showCustomToast">Custom Toast</van-button>
</template>

<script setup>
import { Button as VanButton, showToast } from 'vant'

const showCustomToast = () => {
  showToast({
    type: 'success',
    message: 'Custom toast',
    duration: 3000,
    position: 'top'
  })
}
</script>

Example: Using Toast Component

<template>
  <van-button @click="show = true">Show Toast</van-button>
  <van-toast v-model:show="show" message="Toast message" />
</template>

<script setup>
import { ref } from 'vue'
import { Button as VanButton, Toast as VanToast } from 'vant'

const show = ref(false)
</script>

Key Points

• Use showToast() function for toast messages
• Use showSuccessToast(), showFailToast(), showLoadingToast() for specific types
• Use options object for custom configuration
• Use duration prop for toast duration (milliseconds)
• Use position prop for toast position (top, middle, bottom)
• Use van-toast component for component-based usage
• Toast is available globally via showToast function

Related local files

• API summary: api/components.md
• Dialog comparison: examples/components/dialog.md

Basic Usage | 基本用法

官方文档入口: https://vant-ui.github.io/vant/#/zh-CN 官方对应章节: Quickstart / 快速开始

Instructions

This example demonstrates basic Vant component usage in Vue 3.

Key Concepts

• Using components
• Component props
• Component events
• Composition API

Example: Button Component

<template>
  <van-button type="primary">Primary</van-button>
  <van-button type="success">Success</van-button>
  <van-button type="danger">Danger</van-button>
</template>

<script setup>
import { Button as VanButton } from 'vant'
</script>

Example: Button with Events

<template>
  <van-button type="primary" @click="handleClick">
    Click Me
  </van-button>
</template>

<script setup>
import { Button as VanButton, showToast } from 'vant'

const handleClick = () => {
  showToast('Button clicked!')
}
</script>

Example: Cell Component

<template>
  <van-cell title="Cell Title" value="Content" />
  <van-cell title="Cell Title" value="Content" is-link />
</template>

<script setup>
import { Cell as VanCell } from 'vant'
</script>

Example: Multiple Components

<template>
  <van-card
    num="2"
    price="2.00"
    desc="Description"
    title="Title"
    thumb="https://img.yzcdn.cn/vant/cat.jpeg"
  />
  <van-button type="primary" class="mt-3">Submit</van-button>
</template>

<script setup>
import { Card as VanCard, Button as VanButton } from 'vant'
</script>

Key Points

• Import components from 'vant'
• Use component props to configure behavior
• Use @click for event handling
• Use Composition API with script setup
• Components are optimized for mobile
• Use showToast, showDialog for programmatic APIs

Installation | 安装

官方文档入口: https://vant-ui.github.io/vant/#/zh-CN 官方对应章节: Quickstart / 快速开始

Instructions

This example demonstrates how to install Vant and set it up in a Vue 3 project.

Key Concepts

• Installing Vant
• Importing styles
• Registering components
• Basic setup

Example: Installation

# Using npm
npm install vant

# Using yarn
yarn add vant

# Using pnpm
pnpm add vant

# Using bun
bun add vant

Example: Import Styles

// Import CSS in your entry file (e.g., main.js or main.ts)
import 'vant/lib/index.css'

Example: Full Import

// main.js
import { createApp } from 'vue'
import App from './App.vue'
import Vant from 'vant'
import 'vant/lib/index.css'

const app = createApp(App)
app.use(Vant)
app.mount('#app')

Example: Tree-shaking Import

// main.js
import { createApp } from 'vue'
import App from './App.vue'
import { Button, Cell } from 'vant'
import 'vant/lib/index.css'

const app = createApp(App)
app.use(Button)
app.use(Cell)
app.mount('#app')

Example: TypeScript Setup

// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import Vant from 'vant'
import 'vant/lib/index.css'

const app = createApp(App)
app.use(Vant)
app.mount('#app')

Example: Using unplugin-vue-components

// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import Components from 'unplugin-vue-components/vite'
import { VantResolver } from 'unplugin-vue-components/resolvers'

export default defineConfig({
  plugins: [
    vue(),
    Components({
      resolvers: [VantResolver()],
    }),
  ],
})

Key Points

• Install vant package
• Import Vant CSS in entry file
• Use app.use(Vant) for full import
• Or import components individually for tree-shaking
• Works with both JavaScript and TypeScript
• Use unplugin-vue-components for auto import
• Requires Vue 3

Vant Vue 3 Official Mapping

This file maps the local skill content to the official Vant documentation entry points.

Official entry points

• Official website: https://vant-ui.github.io/
• Official guide: https://vant-ui.github.io/vant/#/zh-CN

Local coverage map

Coverage boundary

This skill does not provide local example files for every Vant component.

Examples of components not covered locally include:

• Tabs
• Tabbar
• NavBar
• Icon
• Image
• Calendar
• Picker
• Grid
• Card
• Badge
• Loading
• ActionSheet

When the user requests one of these:

1. Use the official guide as the primary reference. 2. State clearly that the skill has no dedicated local example file for that component. 3. Follow the coding style already used in this skill:

• Vue 3 script setup
• imports from vant
• mobile-first examples
• concise prop/event explanation

Navigation rule

Only reference local files that actually exist in:

• examples/getting-started/
• examples/components/
• examples/advanced/
• api/
• templates/

Do not mention local files that are not present in the skill directory.

Component Template | 组件模板

使用时机：

• 用户要基于 Vant 快速搭一个新组件
• 已知要用 Vant 组件，但还没有明确的页面骨架
• 需要从通用结构开始，再替换成 Button / Cell / Form / Popup 等具体组件

关联文件：

• api/components.md
• examples/components/button.md
• examples/components/cell.md
• examples/components/form.md

Basic Component Usage

<template>
  <van-component-name
    prop1="value1"
    prop2="value2"
    @event="handleEvent"
  />
</template>

<script setup>
import { ComponentName as VanComponentName } from 'vant'

const handleEvent = () => {
  console.log('Event handled')
}
</script>

Component with v-model

<template>
  <van-field
    v-model="value"
    placeholder="Enter text"
  />
</template>

<script setup>
import { ref } from 'vue'
import { Field as VanField } from 'vant'

const value = ref('')
</script>

Component in Form

<template>
  <van-form @submit="onSubmit">
    <van-field
      v-model="form.field"
      name="field"
      label="Field"
      :rules="[{ required: true, message: 'Please enter field' }]"
    />
    <van-button type="primary" native-type="submit">Submit</van-button>
  </van-form>
</template>

<script setup>
import { ref } from 'vue'
import { Form as VanForm, Field as VanField, Button as VanButton } from 'vant'

const form = ref({
  field: ''
})

const onSubmit = (values) => {
  console.log('Form submitted:', values)
}
</script>

Usage notes

• 优先替换 ComponentName 为当前真实需要的 Vant 组件
• 如果需要校验、提交、重置，优先参考 examples/components/form.md
• 如果需要交互反馈，配合 showToast() 或 showDialog()
• 如果需要全局主题变量，配合 api/config-provider.md

Project Setup Template | 项目设置模板

Basic Vue 3 + Vant Setup

// package.json
{
  "dependencies": {
    "vue": "^3.0.0",
    "vant": "^4.0.0"
  }
}

// main.js
import { createApp } from 'vue'
import App from './App.vue'
import Vant from 'vant'
import 'vant/lib/index.css'

const app = createApp(App)
app.use(Vant)
app.mount('#app')

<!-- App.vue -->
<template>
  <van-config-provider :theme-vars="themeVars">
    <router-view />
  </van-config-provider>
</template>

<script setup>
import { ConfigProvider as VanConfigProvider } from 'vant'

const themeVars = {
  primaryColor: '#07c160'
}
</script>

With TypeScript

// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import Vant from 'vant'
import 'vant/lib/index.css'

const app = createApp(App)
app.use(Vant)
app.mount('#app')

<!-- App.vue -->
<template>
  <van-config-provider :theme-vars="themeVars">
    <router-view />
  </van-config-provider>
</template>

<script setup lang="ts">
import { ConfigProvider as VanConfigProvider } from 'vant'

const themeVars = {
  primaryColor: '#07c160'
}
</script>

With Tree-shaking

// main.js
import { createApp } from 'vue'
import App from './App.vue'
import { Button, Cell, ConfigProvider } from 'vant'
import 'vant/lib/index.css'

const app = createApp(App)
app.use(Button)
app.use(Cell)
app.use(ConfigProvider)
app.mount('#app')

With unplugin-vue-components

// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import Components from 'unplugin-vue-components/vite'
import { VantResolver } from 'unplugin-vue-components/resolvers'

export default defineConfig({
  plugins: [
    vue(),
    Components({
      resolvers: [VantResolver()],
    }),
  ],
})