0
# Display Components
1

2
Components for presenting information including badges, progress indicators, empty states, and media display.
3

4
## Capabilities
5

6
### Badge
7

8
Numerical or status badge component for showing counts or status indicators.
9

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

13
interface BadgeProps {
14
  /** Badge content */
15
  content?: string | number;
16
  /** Maximum number */
17
  max?: number;
18
  /** Show dot instead of content */
19
  dot?: boolean;
20
  /** Badge color */
21
  color?: string;
22
  /** Offset position */
23
  offset?: [number, number];
24
  /** Show zero value */
25
  showZero?: boolean;
26
}
27
```
28

29
### Progress
30

31
Progress bar component for showing completion status.
32

33
```typescript { .api }
34
import { Progress } from 'vant';
35

36
interface ProgressProps {
37
  /** Progress percentage */
38
  percentage?: number;
39
  /** Stroke width */
40
  strokeWidth?: string | number;
41
  /** Progress color */
42
  color?: string | object;
43
  /** Track color */
44
  trackColor?: string;
45
  /** Pivot text */
46
  pivotText?: string;
47
  /** Pivot color */
48
  pivotColor?: string;
49
  /** Show pivot */
50
  showPivot?: boolean;
51
  /** Inactive */
52
  inactive?: boolean;
53
}
54
```
55

56
### Circle
57

58
Circular progress component for showing completion in circular form.
59

60
```typescript { .api }
61
import { Circle } from 'vant';
62

63
interface CircleProps {
64
  /** Current rate */
65
  currentRate?: number;
66
  /** Speed */
67
  speed?: number;
68
  /** Size */
69
  size?: string | number;
70
  /** Color */
71
  color?: string | object;
72
  /** Layer color */
73
  layerColor?: string;
74
  /** Fill */
75
  fill?: string;
76
  /** Stroke width */
77
  strokeWidth?: number;
78
  /** Stroke linecap */
79
  strokeLinecap?: 'butt' | 'round' | 'square';
80
  /** Clockwise */
81
  clockwise?: boolean;
82
  /** Text */
83
  text?: string;
84
}
85
```
86

87
### Empty
88

89
Empty state component for showing when no data is available.
90

91
```typescript { .api }
92
import { Empty } from 'vant';
93

94
interface EmptyProps {
95
  /** Empty image */
96
  image?: string;
97
  /** Image size */
98
  imageSize?: string | number | [string | number, string | number];
99
  /** Description */
100
  description?: string;
101
}
102
```
103

104
### Skeleton
105

106
Skeleton loading component for content placeholders.
107

108
```typescript { .api }
109
import { Skeleton } from 'vant';
110

111
interface SkeletonProps {
112
  /** Number of rows */
113
  row?: number | string;
114
  /** Row width */
115
  rowWidth?: number | string | Array<number | string>;
116
  /** Title */
117
  title?: boolean;
118
  /** Title width */
119
  titleWidth?: number | string;
120
  /** Avatar */
121
  avatar?: boolean;
122
  /** Avatar size */
123
  avatarSize?: number | string;
124
  /** Avatar shape */
125
  avatarShape?: 'square' | 'round';
126
  /** Loading state */
127
  loading?: boolean;
128
  /** Animate */
129
  animate?: boolean;
130
  /** Round */
131
  round?: boolean;
132
}
133
```
134

135
### Tag
136

137
Tag component for labeling and categorization.
138

139
```typescript { .api }
140
import { Tag } from 'vant';
141

142
interface TagProps {
143
  /** Tag type */
144
  type?: 'default' | 'primary' | 'success' | 'warning' | 'danger';
145
  /** Tag size */
146
  size?: 'large' | 'medium' | 'small';
147
  /** Tag color */
148
  color?: string;
149
  /** Show tag */
150
  show?: boolean;
151
  /** Plain style */
152
  plain?: boolean;
153
  /** Round style */
154
  round?: boolean;
155
  /** Mark style */
156
  mark?: boolean;
157
  /** Text color */
158
  textColor?: string;
159
  /** Closeable */
160
  closeable?: boolean;
161
}
162
```
163

164
### NoticeBar
165

166
Notice bar component for displaying important messages.
167

168
```typescript { .api }
169
import { NoticeBar } from 'vant';
170

171
interface NoticeBarProps {
172
  /** Notice mode */
173
  mode?: 'closeable' | 'link';
174
  /** Notice text */
175
  text?: string;
176
  /** Text color */
177
  color?: string;
178
  /** Background color */
179
  background?: string;
180
  /** Left icon */
181
  leftIcon?: string;
182
  /** Delay */
183
  delay?: number | string;
184
  /** Speed */
185
  speed?: number | string;
186
  /** Scrollable */
187
  scrollable?: boolean | null;
188
  /** Wrapable */
189
  wrapable?: boolean;
190
}
191
```
192

193
### TextEllipsis
194

195
Text ellipsis component with multi-line truncation and expand/collapse functionality.
196

197
```typescript { .api }
198
import { TextEllipsis } from 'vant';
199

200
interface TextEllipsisProps {
201
  /** Number of rows to display */
202
  rows?: string | number;
203
  /** Ellipsis dots text */
204
  dots?: string;
205
  /** Text content */
206
  content?: string;
207
  /** Expand button text */
208
  expandText?: string;
209
  /** Collapse button text */
210
  collapseText?: string;
211
  /** Ellipsis position */
212
  position?: 'start' | 'middle' | 'end';
213
}
214

215
// Events
216
interface TextEllipsisEvents {
217
  /** Triggered when action button is clicked */
218
  clickAction: (event: MouseEvent) => void;
219
}
220

221
// Instance methods
222
interface TextEllipsisInstance {
223
  /** Toggle expand/collapse state */
224
  toggle: (expanded?: boolean) => void;
225
}
226
```
227

228
**Usage Example:**
229

230
```vue
231
<template>
232
  <div>
233
    <!-- Basic ellipsis -->
234
    <van-text-ellipsis
235
      rows="3"
236
      content="This is a very long text that will be truncated after 3 lines and show ellipsis with expand functionality"
237
      expand-text="Expand"
238
      collapse-text="Collapse"
239
    />
240
    
241
    <!-- Custom action slot -->
242
    <van-text-ellipsis 
243
      :content="longText"
244
      rows="2"
245
      @click-action="handleAction"
246
    >
247
      <template #action="{ expanded }">
248
        <span class="custom-action">
249
          {{ expanded ? 'Show Less' : 'Show More' }}
250
        </span>
251
      </template>
252
    </van-text-ellipsis>
253
  </div>
254
</template>
255

256
<script setup lang="ts">
257
import { ref } from 'vue';
258
import { TextEllipsis } from 'vant';
259

260
const longText = ref('Very long text content here...');
261

262
const handleAction = (event: MouseEvent) => {
263
  console.log('Action clicked:', event);
264
};
265
</script>
266
```
267

268
### Watermark
269

270
Watermark component for adding watermarks to content with text or image.
271

272
```typescript { .api }
273
import { Watermark } from 'vant';
274

275
interface WatermarkProps {
276
  /** Width of watermark */
277
  width?: number;
278
  /** Height of watermark */
279
  height?: number;
280
  /** Horizontal gap between watermarks */
281
  gapX?: number;
282
  /** Vertical gap between watermarks */
283
  gapY?: number;
284
  /** Rotation angle */
285
  rotate?: string | number;
286
  /** Watermark image URL */
287
  image?: string;
288
  /** Z-index */
289
  zIndex?: string | number;
290
  /** Text content */
291
  content?: string;
292
  /** Opacity */
293
  opacity?: string | number;
294
  /** Full page watermark */
295
  fullPage?: boolean;
296
  /** Text color */
297
  textColor?: string;
298
}
299
```
300

301
**Usage Example:**
302

303
```vue
304
<template>
305
  <div>
306
    <!-- Text watermark -->
307
    <van-watermark content="Vant Watermark">
308
      <div class="content">
309
        <p>Protected content here</p>
310
      </div>
311
    </van-watermark>
312
    
313
    <!-- Image watermark -->
314
    <van-watermark 
315
      :image="logoUrl"
316
      :width="120"
317
      :height="64"
318
      :opacity="0.3"
319
    >
320
      <div class="content">
321
        <p>Content with image watermark</p>
322
      </div>
323
    </van-watermark>
324
    
325
    <!-- Custom content watermark -->
326
    <van-watermark :gap-x="50" :gap-y="50">
327
      <template #content>
328
        <div class="custom-watermark">
329
          <van-icon name="shield-o" />
330
          <span>Custom</span>
331
        </div>
332
      </template>
333
      <div class="content">
334
        <p>Content with custom watermark</p>
335
      </div>
336
    </van-watermark>
337
  </div>
338
</template>
339

340
<script setup lang="ts">
341
import { Watermark, Icon } from 'vant';
342

343
const logoUrl = 'https://example.com/logo.png';
344
</script>
345
```
346

347
### Swipe
348

349
Swipe component for carousel and image galleries.
350

351
```typescript { .api }
352
import { Swipe, SwipeItem } from 'vant';
353

354
interface SwipeProps {
355
  /** Auto play */
356
  autoplay?: number | string;
357
  /** Duration */
358
  duration?: number | string;
359
  /** Initial swipe */
360
  initialSwipe?: number | string;
361
  /** Show indicators */
362
  showIndicators?: boolean;
363
  /** Indicator color */
364
  indicatorColor?: string;
365
  /** Loop */
366
  loop?: boolean;
367
  /** Touchable */
368
  touchable?: boolean;
369
  /** Vertical */
370
  vertical?: boolean;
371
  /** Stop propagation */
372
  stopPropagation?: boolean;
373
}
374
```
375

376
### ImagePreview
377

378
Image preview component with zoom and navigation.
379

380
```typescript { .api }
381
import { ImagePreview } from 'vant';
382

383
// Function API
384
function ImagePreview(images: string[]): ImagePreviewInstance;
385
function ImagePreview(options: ImagePreviewOptions): ImagePreviewInstance;
386

387
interface ImagePreviewOptions {
388
  /** Image URLs */
389
  images?: string[];
390
  /** Start position */
391
  startPosition?: number;
392
  /** Swipe duration */
393
  swipeDuration?: number;
394
  /** Show index */
395
  showIndex?: boolean;
396
  /** Show indicators */
397
  showIndicators?: boolean;
398
  /** Loop */
399
  loop?: boolean;
400
  /** Close on popstate */
401
  closeOnPopstate?: boolean;
402
  /** Class name */
403
  className?: string;
404
  /** Max zoom */
405
  maxZoom?: number;
406
  /** Min zoom */
407
  minZoom?: number;
408
  /** Close icon name */
409
  closeIcon?: string;
410
  /** Close icon position */
411
  closeIconPosition?: 'top-left' | 'top-right';
412
  /** Transition */
413
  transition?: string;
414
  /** Overlay style */
415
  overlayStyle?: object;
416
}
417

418
interface ImagePreviewInstance {
419
  close: () => void;
420
  swipeTo: (index: number) => void;
421
}
422
```
423

424
### List
425

426
List component with pull-to-refresh and infinite loading.
427

428
```typescript { .api }
429
import { List } from 'vant';
430

431
interface ListProps {
432
  /** Loading state */
433
  loading?: boolean;
434
  /** Finished state */
435
  finished?: boolean;
436
  /** Finished text */
437
  finishedText?: string;
438
  /** Loading text */
439
  loadingText?: string;
440
  /** Error state */
441
  error?: boolean;
442
  /** Error text */
443
  errorText?: string;
444
  /** Offset */
445
  offset?: number | string;
446
  /** Direction */
447
  direction?: 'up' | 'down';
448
  /** Immediate check */
449
  immediateCheck?: boolean;
450
}
451
```