0
# Basic Components
1

2
Core UI building blocks for creating mobile interfaces. These fundamental components provide the foundation for buttons, navigation cells, icons, images, layout, and basic interaction patterns.
3

4
## Capabilities
5

6
### Button
7

8
Versatile button component with multiple types, sizes, and states for user interactions.
9

10
```typescript { .api }
11
import { Button } from 'vant';
12

13
interface ButtonProps {
14
  /** Button type affecting appearance */
15
  type?: 'default' | 'primary' | 'success' | 'warning' | 'danger';
16
  /** Button size */
17
  size?: 'large' | 'normal' | 'small' | 'mini';
18
  /** Button text content */
19
  text?: string;
20
  /** Icon name to display */
21
  icon?: string;
22
  /** Icon position relative to text */
23
  iconPosition?: 'left' | 'right';
24
  /** Loading state */
25
  loading?: boolean;
26
  /** Disabled state */
27
  disabled?: boolean;
28
  /** Plain style button */
29
  plain?: boolean;
30
  /** Hairline border */
31
  hairline?: boolean;
32
  /** Square shape */
33
  square?: boolean;
34
  /** Round shape */
35
  round?: boolean;
36
  /** Block level button */
37
  block?: boolean;
38
  /** Custom color */
39
  color?: string;
40
  /** Button tag type */
41
  tag?: keyof HTMLElementTagMap;
42
  /** Native button type */
43
  nativeType?: 'button' | 'submit' | 'reset';
44
}
45

46
// Events
47
interface ButtonEvents {
48
  /** Triggered when button is clicked */
49
  click: (event: MouseEvent) => void;
50
  /** Triggered when touch starts */
51
  touchstart: (event: TouchEvent) => void;
52
}
53
```
54

55
**Usage Example:**
56

57
```vue
58
<template>
59
  <div>
60
    <!-- Basic button -->
61
    <van-button type="primary">Primary Button</van-button>
62
    
63
    <!-- Button with icon -->
64
    <van-button type="primary" icon="plus" @click="handleClick">
65
      Add Item
66
    </van-button>
67
    
68
    <!-- Loading button -->
69
    <van-button type="primary" :loading="loading" @click="handleSubmit">
70
      Submit
71
    </van-button>
72
    
73
    <!-- Disabled button -->
74
    <van-button type="primary" disabled>Disabled</van-button>
75
  </div>
76
</template>
77

78
<script setup lang="ts">
79
import { ref } from 'vue';
80
import { Button } from 'vant';
81

82
const loading = ref(false);
83

84
const handleClick = () => {
85
  console.log('Button clicked');
86
};
87

88
const handleSubmit = async () => {
89
  loading.value = true;
90
  // Simulate API call
91
  await new Promise(resolve => setTimeout(resolve, 2000));
92
  loading.value = false;
93
};
94
</script>
95
```
96

97
### Cell
98

99
List item component for displaying structured information with titles, values, and navigation.
100

101
```typescript { .api }
102
import { Cell } from 'vant';
103

104
interface CellProps {
105
  /** Left side title */
106
  title?: string | number;
107
  /** Right side value */
108
  value?: string | number;
109
  /** Description text below title */
110
  label?: string;
111
  /** Left icon name */
112
  icon?: string;
113
  /** Right icon name */
114
  rightIcon?: string;
115
  /** Cell size */
116
  size?: 'large' | 'normal';
117
  /** URL to navigate to */
118
  url?: string;
119
  /** Route object for vue-router */
120
  to?: string | object;
121
  /** Replace current route */
122
  replace?: boolean;
123
  /** Enable click feedback */
124
  clickable?: boolean;
125
  /** Whether to show arrow */
126
  isLink?: boolean;
127
  /** Required field marker */
128
  required?: boolean;
129
  /** Center content vertically */
130
  center?: boolean;
131
  /** Arrow direction */
132
  arrowDirection?: 'left' | 'up' | 'down' | 'right';
133
  /** Title text color */
134
  titleStyle?: string | object;
135
  /** Title class name */
136
  titleClass?: string;
137
  /** Value text color */
138
  valueStyle?: string | object;
139
  /** Value class name */
140
  valueClass?: string;
141
  /** Label text color */
142
  labelStyle?: string | object;
143
  /** Label class name */
144
  labelClass?: string;
145
}
146

147
// Events
148
interface CellEvents {
149
  /** Triggered when cell is clicked */
150
  click: (event: MouseEvent) => void;
151
}
152

153
// Slots
154
interface CellSlots {
155
  /** Custom title content */
156
  title?: () => VNode[];
157
  /** Custom value content */
158
  default?: () => VNode[];
159
  /** Custom label content */
160
  label?: () => VNode[];
161
  /** Custom left icon */
162
  icon?: () => VNode[];
163
  /** Custom right icon */
164
  'right-icon'?: () => VNode[];
165
  /** Extra content */
166
  extra?: () => VNode[];
167
}
168
```
169

170
**Usage Example:**
171

172
```vue
173
<template>
174
  <van-cell-group>
175
    <!-- Basic cell -->
176
    <van-cell title="Cell title" value="Content" />
177
    
178
    <!-- Cell with description -->
179
    <van-cell title="Cell title" value="Content" label="Description" />
180
    
181
    <!-- Cell with icon -->
182
    <van-cell title="Cell title" value="Content" icon="location-o" />
183
    
184
    <!-- Clickable cell -->
185
    <van-cell 
186
      title="Click me" 
187
      is-link 
188
      @click="handleCellClick"
189
    />
190
    
191
    <!-- Cell with custom slot -->
192
    <van-cell title="Custom content" value="Content">
193
      <template #right-icon>
194
        <van-icon name="search" class="custom-icon" />
195
      </template>
196
    </van-cell>
197
  </van-cell-group>
198
</template>
199

200
<script setup lang="ts">
201
import { Cell, CellGroup, Icon } from 'vant';
202

203
const handleCellClick = () => {
204
  console.log('Cell clicked');
205
};
206
</script>
207
```
208

209
### CellGroup
210

211
Container component for grouping related cells with optional title and inset styling.
212

213
```typescript { .api }
214
import { CellGroup } from 'vant';
215

216
interface CellGroupProps {
217
  /** Group title */
218
  title?: string;
219
  /** Inset style with rounded corners */
220
  inset?: boolean;
221
  /** Custom border style */
222
  border?: boolean;
223
}
224

225
// Slots
226
interface CellGroupSlots {
227
  /** Cell group content */
228
  default?: () => VNode[];
229
  /** Custom title content */
230
  title?: () => VNode[];
231
}
232
```
233

234
### Icon
235

236
Icon component supporting both built-in and custom icons with various sizes and colors.
237

238
```typescript { .api }
239
import { Icon } from 'vant';
240

241
interface IconProps {
242
  /** Icon name */
243
  name: string;
244
  /** Icon color */
245
  color?: string;
246
  /** Icon size */
247
  size?: string | number;
248
  /** Class prefix for custom icons */
249
  classPrefix?: string;
250
  /** Custom tag type */
251
  tag?: keyof HTMLElementTagMap;
252
  /** Badge content */
253
  badge?: string | number;
254
  /** Show badge dot */
255
  dot?: boolean;
256
}
257
```
258

259
**Usage Example:**
260

261
```vue
262
<template>
263
  <div>
264
    <!-- Basic icon -->
265
    <van-icon name="chat-o" />
266
    
267
    <!-- Icon with color and size -->
268
    <van-icon name="chat-o" color="#1989fa" size="20px" />
269
    
270
    <!-- Icon with badge -->
271
    <van-icon name="chat-o" badge="9" />
272
    <van-icon name="chat-o" dot />
273
  </div>
274
</template>
275
```
276

277
### Image
278

279
Enhanced image component with lazy loading, error handling, and multiple fit modes.
280

281
```typescript { .api }
282
import { Image } from 'vant';
283

284
interface ImageProps {
285
  /** Image source URL */
286
  src?: string;
287
  /** Image fit mode */
288
  fit?: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down';
289
  /** Alt text */
290
  alt?: string;
291
  /** Image width */
292
  width?: string | number;
293
  /** Image height */
294
  height?: string | number;
295
  /** Border radius */
296
  radius?: string | number;
297
  /** Round shape */
298
  round?: boolean;
299
  /** Enable lazy loading */
300
  lazyLoad?: boolean;
301
  /** Show loading placeholder */
302
  showLoading?: boolean;
303
  /** Show error placeholder */
304
  showError?: boolean;
305
  /** Error icon */
306
  errorIcon?: string;
307
  /** Loading icon */
308
  loadingIcon?: string;
309
  /** Icon size for placeholder */
310
  iconSize?: string | number;
311
  /** Icon prefix */
312
  iconPrefix?: string;
313
}
314

315
// Events
316
interface ImageEvents {
317
  /** Triggered when image loads successfully */
318
  load: (event: Event) => void;
319
  /** Triggered when image fails to load */
320
  error: (event: Event) => void;
321
  /** Triggered when image is clicked */
322
  click: (event: MouseEvent) => void;
323
}
324
```
325

326
### Layout Components (Row & Col)
327

328
Flexible grid system based on 24-column layout for responsive design.
329

330
```typescript { .api }
331
import { Row, Col } from 'vant';
332

333
interface RowProps {
334
  /** Grid type */
335
  type?: 'flex';
336
  /** Horizontal alignment */
337
  justify?: 'start' | 'end' | 'center' | 'space-around' | 'space-between';
338
  /** Vertical alignment */
339
  align?: 'top' | 'middle' | 'bottom';
340
  /** Whether to wrap */
341
  wrap?: boolean;
342
  /** Column gap */
343
  gutter?: string | number | Array<string | number>;
344
  /** Custom tag */
345
  tag?: keyof HTMLElementTagMap;
346
}
347

348
interface ColProps {
349
  /** Column span */
350
  span?: string | number;
351
  /** Column offset */
352
  offset?: string | number;
353
  /** Custom tag */
354
  tag?: keyof HTMLElementTagMap;
355
}
356
```
357

358
**Usage Example:**
359

360
```vue
361
<template>
362
  <div>
363
    <!-- Basic grid -->
364
    <van-row>
365
      <van-col span="8">Col 8</van-col>
366
      <van-col span="8">Col 8</van-col>
367
      <van-col span="8">Col 8</van-col>
368
    </van-row>
369
    
370
    <!-- Grid with gutter -->
371
    <van-row gutter="20">
372
      <van-col span="6">Col 6</van-col>
373
      <van-col span="6">Col 6</van-col>
374
      <van-col span="6">Col 6</van-col>
375
      <van-col span="6">Col 6</van-col>
376
    </van-row>
377
    
378
    <!-- Flex layout -->
379
    <van-row type="flex" justify="center" align="middle">
380
      <van-col span="6">Centered</van-col>
381
      <van-col span="6">Content</van-col>
382
    </van-row>
383
  </div>
384
</template>
385
```
386

387
### Popup
388

389
Modal popup container with flexible positioning and animation options.
390

391
```typescript { .api }
392
import { Popup } from 'vant';
393

394
interface PopupProps {
395
  /** Show/hide popup */
396
  show?: boolean;
397
  /** Popup position */
398
  position?: 'top' | 'bottom' | 'right' | 'left' | 'center';
399
  /** Show overlay */
400
  overlay?: boolean;
401
  /** Overlay class */
402
  overlayClass?: string;
403
  /** Overlay style */
404
  overlayStyle?: object;
405
  /** Close on overlay click */
406
  closeOnClickOverlay?: boolean;
407
  /** Z-index */
408
  zIndex?: string | number;
409
  /** Animation duration */
410
  duration?: string | number;
411
  /** Border radius */
412
  round?: boolean;
413
  /** Lock scroll */
414
  lockScroll?: boolean;
415
  /** Show close icon */
416
  closeable?: boolean;
417
  /** Close icon name */
418
  closeIcon?: string;
419
  /** Close icon position */
420
  closeIconPosition?: 'top-left' | 'top-right';
421
  /** Transition name */
422
  transition?: string;
423
  /** Safe area inset bottom */
424
  safeAreaInsetBottom?: boolean;
425
  /** Safe area inset top */
426
  safeAreaInsetTop?: boolean;
427
}
428
```
429

430
### Space
431

432
Component for managing spacing between child elements.
433

434
```typescript { .api }
435
import { Space } from 'vant';
436

437
interface SpaceProps {
438
  /** Direction of arrangement */
439
  direction?: 'horizontal' | 'vertical';
440
  /** Spacing size */
441
  size?: string | number | [string | number, string | number];
442
  /** Alignment */
443
  align?: 'start' | 'end' | 'center' | 'baseline';
444
  /** Whether to wrap */
445
  wrap?: boolean;
446
  /** Fill container */
447
  fill?: boolean;
448
}
449
```
450

451
### Toast
452

453
Lightweight message prompt component for showing brief messages.
454

455
```typescript { .api }
456
import { Toast } from 'vant';
457

458
// Function API
459
function Toast(message: string): ToastInstance;
460
function Toast(options: ToastOptions): ToastInstance;
461

462
interface ToastOptions {
463
  /** Toast type */
464
  type?: 'text' | 'loading' | 'success' | 'fail' | 'html';
465
  /** Toast message */
466
  message?: string;
467
  /** Display position */
468
  position?: 'top' | 'middle' | 'bottom';
469
  /** Display duration (ms) */
470
  duration?: number;
471
  /** Custom class name */
472
  className?: string;
473
  /** Prevent touch events */
474
  forbidClick?: boolean;
475
  /** Loading type */
476
  loadingType?: 'circular' | 'spinner';
477
  /** Show overlay */
478
  overlay?: boolean;
479
  /** Close on overlay click */
480
  closeOnClickOverlay?: boolean;
481
  /** Transition name */
482
  transition?: string;
483
  /** Icon name */
484
  icon?: string;
485
  /** Icon size */
486
  iconSize?: string | number;
487
  /** Icon prefix */
488
  iconPrefix?: string;
489
  /** Z-index */
490
  zIndex?: number;
491
}
492

493
interface ToastInstance {
494
  /** Close toast */
495
  close: () => void;
496
}
497

498
// Static methods and exports
499
namespace Toast {
500
  function loading(message?: string): ToastInstance;
501
  function success(message?: string): ToastInstance;
502
  function fail(message?: string): ToastInstance;
503
  function clear(): void;
504
  function setDefaultOptions(options: ToastOptions): void;
505
  function resetDefaultOptions(): void;
506
}
507

508
// Additional function exports
509
function showToast(options: string | ToastOptions): ToastInstance;
510
function closeToast(all?: boolean): void;
511
function showFailToast(options: string | ToastOptions): ToastInstance;
512
function showLoadingToast(options: string | ToastOptions): ToastInstance;
513
function showSuccessToast(options: string | ToastOptions): ToastInstance;
514
function allowMultipleToast(allow?: boolean): void;
515
function setToastDefaultOptions(options: ToastOptions): void;
516
function resetToastDefaultOptions(): void;
517
```
518

519
**Usage Example:**
520

521
```vue
522
<template>
523
  <div>
524
    <van-button @click="showToast">Show Toast</van-button>
525
    <van-button @click="showLoading">Show Loading</van-button>
526
    <van-button @click="showSuccess">Show Success</van-button>
527
  </div>
528
</template>
529

530
<script setup lang="ts">
531
import { Toast } from 'vant';
532

533
const showToast = () => {
534
  Toast('Some message');
535
};
536

537
const showLoading = () => {
538
  const toast = Toast.loading({
539
    message: 'Loading...',
540
    forbidClick: true,
541
  });
542
  
543
  // Close after 3 seconds
544
  setTimeout(() => {
545
    toast.close();
546
  }, 3000);
547
};
548

549
const showSuccess = () => {
550
  Toast.success('Success!');
551
};
552
</script>
553
```
554

555
### ConfigProvider
556

557
Global configuration component for theming and customization.
558

559
```typescript { .api }
560
import { ConfigProvider } from 'vant';
561

562
interface ConfigProviderProps {
563
  /** Theme mode */
564
  theme?: 'light' | 'dark';
565
  /** Theme color variables */
566
  themeVars?: Record<string, string>;
567
  /** Icon class prefix */
568
  iconPrefix?: string;
569
  /** Component tag prefix */
570
  tag?: string;
571
}
572
```
573

574
### Divider
575

576
Visual separator component for dividing content with optional text.
577

578
```typescript { .api }
579
import { Divider } from 'vant';
580

581
interface DividerProps {
582
  /** Dashed border style */
583
  dashed?: boolean;
584
  /** Hairline border style */
585
  hairline?: boolean;
586
  /** Vertical orientation */
587
  vertical?: boolean;
588
  /** Content position for horizontal dividers */
589
  contentPosition?: 'left' | 'center' | 'right';
590
}
591
```
592

593
**Usage Example:**
594

595
```vue
596
<template>
597
  <div>
598
    <!-- Basic divider -->
599
    <van-divider />
600
    
601
    <!-- Divider with text -->
602
    <van-divider>Text</van-divider>
603
    
604
    <!-- Dashed divider -->
605
    <van-divider dashed>Dashed</van-divider>
606
    
607
    <!-- Custom content position -->
608
    <van-divider content-position="left">Left</van-divider>
609
    <van-divider content-position="right">Right</van-divider>
610
    
611
    <!-- Vertical divider -->
612
    <van-divider vertical />
613
  </div>
614
</template>
615
```
616

617
### BackTop
618

619
Back to top button with smooth scrolling and customizable positioning.
620

621
```typescript { .api }
622
import { BackTop } from 'vant';
623

624
interface BackTopProps {
625
  /** Right offset */
626
  right?: string | number;
627
  /** Bottom offset */
628
  bottom?: string | number;
629
  /** Z-index */
630
  zIndex?: string | number;
631
  /** Scroll target selector or element */
632
  target?: string | Element;
633
  /** Scroll offset to show button */
634
  offset?: string | number;
635
  /** Immediate scroll without animation */
636
  immediate?: boolean;
637
  /** Teleport target */
638
  teleport?: string | Element;
639
}
640

641
// Events
642
interface BackTopEvents {
643
  /** Triggered when back to top button is clicked */
644
  click: (event: MouseEvent) => void;
645
}
646
```
647

648
**Usage Example:**
649

650
```vue
651
<template>
652
  <div>
653
    <!-- Basic back to top -->
654
    <van-back-top />
655
    
656
    <!-- Custom position and offset -->
657
    <van-back-top
658
      :right="20"
659
      :bottom="100"
660
      :offset="300"
661
      @click="handleBackTop"
662
    />
663
    
664
    <!-- Custom content -->
665
    <van-back-top>
666
      <div class="custom-back-top">
667
        <van-icon name="arrow-up" />
668
      </div>
669
    </van-back-top>
670
  </div>
671
</template>
672

673
<script setup lang="ts">
674
import { BackTop, Icon } from 'vant';
675

676
const handleBackTop = () => {
677
  console.log('Back to top clicked');
678
};
679
</script>
680
```
681

682
### Overlay
683

684
Modal overlay component providing backdrop for popups and modals.
685

686
```typescript { .api }
687
import { Overlay } from 'vant';
688

689
interface OverlayProps {
690
  /** Show/hide overlay */
691
  show?: boolean;
692
  /** Z-index */
693
  zIndex?: string | number;
694
  /** Custom class name */
695
  className?: string;
696
  /** Custom style */
697
  customStyle?: object;
698
  /** Animation duration */
699
  duration?: string | number;
700
  /** Lock scroll */
701
  lockScroll?: boolean;
702
}
703

704
// Events
705
interface OverlayEvents {
706
  /** Triggered when overlay is clicked */
707
  click: (event: MouseEvent) => void;
708
}
709
```
710

711
### Sticky
712

713
Sticky positioning component that fixes elements during scroll.
714

715
```typescript { .api }
716
import { Sticky } from 'vant';
717

718
interface StickyProps {
719
  /** Z-index when sticky */
720
  zIndex?: string | number;
721
  /** Container selector */
722
  container?: Element;
723
  /** Offset from top when sticky */
724
  offsetTop?: string | number;
725
  /** Offset from bottom when sticky */
726
  offsetBottom?: string | number;
727
  /** Sticky position */
728
  position?: 'top' | 'bottom';
729
}
730

731
// Events
732
interface StickyEvents {
733
  /** Triggered when sticky state changes */
734
  change: (isFixed: boolean) => void;
735
  /** Triggered when scrolling */
736
  scroll: (scrollTop: number, isFixed: boolean) => void;
737
}
738
```