0
# Vant
1

2
Vant is a lightweight, customizable Vue 3 mobile UI component library with 100+ components designed for mobile web applications. It provides a comprehensive set of high-quality components following mobile design patterns, with full TypeScript support and extensive customization options.
3

4
## Package Information
5

6
- **Package Name**: vant
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Framework**: Vue 3
10
- **Installation**: `npm install vant`
11

12
## Core Imports
13

14
```typescript
15
import { createApp } from 'vue';
16
import { Button, Cell, Icon } from 'vant';
17
import 'vant/lib/index.css';
18
```
19

20
Global installation:
21

22
```typescript
23
import { createApp } from 'vue';
24
import Vant from 'vant';
25
import 'vant/lib/index.css';
26

27
const app = createApp();
28
app.use(Vant);
29
```
30

31
Individual component imports:
32

33
```typescript
34
import { Button, Toast, Dialog } from 'vant';
35
```
36

37
## Basic Usage
38

39
```typescript
40
<template>
41
  <div>
42
    <!-- Basic button usage -->
43
    <van-button type="primary" @click="showToast">Click Me</van-button>
44
    
45
    <!-- Cell list -->
46
    <van-cell-group>
47
      <van-cell title="Cell title" value="Content" />
48
      <van-cell title="Cell title" value="Content" label="Description" />
49
    </van-cell-group>
50
    
51
    <!-- Form field -->
52
    <van-field
53
      v-model="username"
54
      placeholder="Username"
55
      left-icon="contact"
56
    />
57
  </div>
58
</template>
59

60
<script setup lang="ts">
61
import { ref } from 'vue';
62
import { Button, Cell, CellGroup, Field, Toast } from 'vant';
63

64
const username = ref('');
65

66
const showToast = () => {
67
  Toast('Hello Vant!');
68
};
69
</script>
70
```
71

72
## Architecture
73

74
Vant follows a modular component architecture with several key design patterns:
75

76
- **Component System**: Each component is self-contained with its own props, events, and slots
77
- **Theme System**: CSS custom properties enable comprehensive theming
78
- **Vue 3 Integration**: Full Composition API support with TypeScript definitions
79
- **Mobile-First**: All components optimized for touch interfaces and mobile viewports
80
- **Tree Shaking**: Individual component imports for optimal bundle sizes
81
- **Accessibility**: WCAG compliance and keyboard navigation support
82

83
## Capabilities
84

85
### Basic Components
86

87
Core UI building blocks including buttons, cells, icons, and layout components. These form the foundation for mobile interfaces.
88

89
```typescript { .api }
90
import { Button, Cell, CellGroup, Icon, Image, Col, Row, Space } from 'vant';
91

92
// Button component with multiple types and sizes
93
interface ButtonProps {
94
  type?: 'default' | 'primary' | 'success' | 'warning' | 'danger';
95
  size?: 'large' | 'normal' | 'small' | 'mini';
96
  text?: string;
97
  icon?: string;
98
  loading?: boolean;
99
  disabled?: boolean;
100
}
101

102
// Cell component for list items
103
interface CellProps {
104
  title?: string;
105
  value?: string;
106
  label?: string;
107
  icon?: string;
108
  size?: 'large' | 'normal';
109
  clickable?: boolean;
110
}
111
```
112

113
[Basic Components](./basic-components.md)
114

115
### Form Components
116

117
Comprehensive form controls including inputs, selectors, and validation components for building complex forms.
118

119
```typescript { .api }
120
import { Field, Checkbox, Radio, Picker, DatePicker, Switch, Stepper } from 'vant';
121

122
// Field component for text input
123
interface FieldProps {
124
  modelValue?: string | number;
125
  type?: 'text' | 'number' | 'password' | 'textarea';
126
  placeholder?: string;
127
  maxlength?: number;
128
  readonly?: boolean;
129
  disabled?: boolean;
130
  required?: boolean;
131
}
132

133
// Checkbox component
134
interface CheckboxProps {
135
  modelValue?: boolean;
136
  disabled?: boolean;
137
  shape?: 'square' | 'round';
138
  iconSize?: string | number;
139
}
140
```
141

142
[Form Components](./form-components.md)
143

144
### Display Components
145

146
Components for presenting information including badges, progress indicators, skeleton screens, and media display.
147

148
```typescript { .api }
149
import { Badge, Progress, Empty, Skeleton, Image, Tag, Circle } from 'vant';
150

151
// Progress component
152
interface ProgressProps {
153
  percentage?: number;
154
  strokeWidth?: string | number;
155
  color?: string;
156
  trackColor?: string;
157
  pivotText?: string;
158
  showPivot?: boolean;
159
}
160

161
// Badge component
162
interface BadgeProps {
163
  content?: string | number;
164
  max?: number;
165
  dot?: boolean;
166
  color?: string;
167
  showZero?: boolean;
168
}
169
```
170

171
[Display Components](./display-components.md)
172

173
### Navigation Components
174

175
Navigation and routing components including tabs, navigation bars, pagination, and sidebar navigation.
176

177
```typescript { .api }
178
import { NavBar, Tab, Tabs, Tabbar, TabbarItem, Pagination, IndexBar } from 'vant';
179

180
// NavBar component
181
interface NavBarProps {
182
  title?: string;
183
  leftText?: string;
184
  rightText?: string;
185
  leftArrow?: boolean;
186
  fixed?: boolean;
187
  placeholder?: boolean;
188
  zIndex?: number;
189
}
190

191
// Tab component
192
interface TabProps {
193
  title?: string;
194
  disabled?: boolean;
195
  dot?: boolean;
196
  badge?: string | number;
197
  name?: string | number;
198
}
199
```
200

201
[Navigation Components](./navigation-components.md)
202

203
### Feedback Components
204

205
Interactive feedback components including dialogs, action sheets, loading states, and toast notifications.
206

207
```typescript { .api }
208
import { Dialog, Toast, ActionSheet, Loading, Notify, Overlay } from 'vant';
209

210
// Dialog API
211
interface DialogOptions {
212
  title?: string;
213
  message?: string;
214
  confirmButtonText?: string;
215
  cancelButtonText?: string;
216
  showCancelButton?: boolean;
217
  overlay?: boolean;
218
  closeOnClickOverlay?: boolean;
219
}
220

221
// Toast API
222
interface ToastOptions {
223
  message: string;
224
  type?: 'text' | 'loading' | 'success' | 'fail' | 'html';
225
  position?: 'top' | 'middle' | 'bottom';
226
  duration?: number;
227
  forbidClick?: boolean;
228
}
229
```
230

231
[Feedback Components](./feedback-components.md)
232

233
### Business Components
234

235
Specialized components for e-commerce and business applications including address management, coupons, and product cards.
236

237
```typescript { .api }
238
import { AddressEdit, AddressList, Card, Coupon, CouponList, SubmitBar } from 'vant';
239

240
// AddressEdit component
241
interface AddressEditProps {
242
  addressInfo?: AddressEditInfo;
243
  areaList?: Record<string, any>;
244
  showArea?: boolean;
245
  showPostal?: boolean;
246
  showSetDefault?: boolean;
247
}
248

249
// Card component
250
interface CardProps {
251
  thumb?: string;
252
  title?: string;
253
  desc?: string;
254
  price?: string | number;
255
  originPrice?: string | number;
256
  centered?: boolean;
257
}
258
```
259

260
[Business Components](./business-components.md)
261

262
### Utilities and Composables
263

264
Utility functions and Vue 3 composables for common functionality including DOM manipulation, touch handling, and state management.
265

266
```typescript { .api }
267
import { useRect, useScrollParent, useEventListener, useToggle } from 'vant';
268

269
// Rect utility for element dimensions
270
function useRect(elementOrSelector: Element | Window | string): {
271
  width: number;
272
  height: number;
273
  top: number;
274
  left: number;
275
  right: number;
276
  bottom: number;
277
};
278

279
// Toggle state management
280
function useToggle(defaultValue?: boolean): [
281
  Ref<boolean>,
282
  (value?: boolean) => void
283
];
284
```
285

286
[Utilities and Composables](./utilities-composables.md)
287

288
## Types
289

290
Common type definitions used throughout the Vant ecosystem.
291

292
```typescript { .api }
293
// Theme variables interface
294
interface ConfigProviderTheme {
295
  primaryColor?: string;
296
  successColor?: string;
297
  dangerColor?: string;
298
  warningColor?: string;
299
  textColor?: string;
300
  activeColor?: string;
301
  backgroundColor?: string;
302
  borderColor?: string;
303
}
304

305
// Component size types
306
type ComponentSize = 'large' | 'normal' | 'small' | 'mini';
307

308
// Theme mode
309
type ThemeMode = 'light' | 'dark';
310

311
// Event handler types
312
type EventHandler<T = Event> = (event: T) => void;
313
```