Vben Descriptions
Descriptions displays a group of read-only fields, commonly used on detail pages and information previews. It is built on shadcn-ui with an API modeled after Ant Design Vue's Descriptions, supporting responsive columns, column spanning, borders, and vertical layout.
If the documentation does not cover the details you need, please refer to the online examples.
Before you start
The component supports two usages: data-driven via items (recommended), or declaring entries with the VbenDescriptionsItem child component. items takes precedence when both are provided. :::
Basic Usage
Pass an array of fields via items, each with a label and content. Columns adapt to breakpoints by default (1 column on xs, 2 on sm, 3 on md and above).
<script lang="ts" setup>
import { VbenDescriptions } from '@vben/common-ui';
const items = [
{ content: 'Vben', label: '用户名' },
{ content: '13800138000', label: '手机号' },
{ content: '中国 · 杭州', label: '居住地' },
{ content: '前端工程师', label: '职位' },
{
content: '这是一段较长的备注信息，用于演示跨列展示。',
label: '备注',
span: 3,
},
];
</script>
<template>
<VbenDescriptions :items="items" />
</template>Bordered
Set bordered for a bordered style, combined with the title prop and the #extra slot (an action area on the right of the title).
<script lang="ts" setup>
import { VbenDescriptions } from '@vben/common-ui';
const items = [
{ content: 'Vben', label: '用户名' },
{ content: '13800138000', label: '手机号' },
{ content: '正常', label: '状态' },
{ content: '中国 · 杭州', label: '居住地' },
{
content: '浙江省杭州市西湖区某某街道某某小区 1 幢 2 单元',
label: '地址',
span: 3,
},
];
</script>
<template>
<VbenDescriptions bordered title="用户信息" :items="items">
<template #extra>
<span style="color: #1677ff; cursor: pointer">编辑</span>
</template>
</VbenDescriptions>
</template>Vertical Layout
Use layout="vertical" to place labels above their content.
<script lang="ts" setup>
import { VbenDescriptions } from '@vben/common-ui';
const items = [
{ content: 'Vben', label: '用户名' },
{ content: '13800138000', label: '手机号' },
{ content: '中国 · 杭州', label: '居住地' },
{ content: '这是一段较长的备注信息。', label: '备注', span: 3 },
];
</script>
<template>
<VbenDescriptions bordered layout="vertical" :items="items" />
</template>Sizes
Use size to switch between small, middle, and large.
<script lang="ts" setup>
import { VbenDescriptions } from '@vben/common-ui';
const items = [
{ content: 'Vben', label: '用户名' },
{ content: '13800138000', label: '手机号' },
{ content: '中国 · 杭州', label: '居住地' },
{ content: '前端工程师', label: '职位' },
];
</script>
<template>
<div style="display: flex; flex-direction: column; gap: 16px">
<VbenDescriptions
size="small"
bordered
title="Small"
:column="2"
:items="items"
/>
<VbenDescriptions
size="middle"
bordered
title="Middle"
:column="2"
:items="items"
/>
<VbenDescriptions
size="large"
bordered
title="Large"
:column="2"
:items="items"
/>
</div>
</template>Span & Responsive
Set span on an item to span multiple columns; 'filled' fills the remaining space of the current row. column accepts a breakpoint-keyed object for responsive columns.
<script lang="ts" setup>
import { VbenDescriptions } from '@vben/common-ui';
const items = [
{ content: '1', label: 'A' },
{ content: '2（span: 2）', label: 'B', span: 2 },
{ content: '3', label: 'C' },
{ content: '占满当前行剩余空间', label: 'D（span: filled）', span: 'filled' },
{ content: '5', label: 'E' },
];
</script>
<template>
<!-- 列数随断点变化：xs 1 列、sm 2 列、md 及以上 3 列 -->
<VbenDescriptions bordered :column="{ md: 3, sm: 2, xs: 1 }" :items="items" />
</template>Child Component Usage
When items is omitted, declare entries with VbenDescriptionsItem in the default slot. Content can be customized via the default slot or the #content slot.
<script lang="ts" setup>
import { VbenDescriptions, VbenDescriptionsItem } from '@vben/common-ui';
</script>
<template>
<!-- 通过子组件 VbenDescriptionsItem 声明列表项 -->
<VbenDescriptions bordered :column="2">
<VbenDescriptionsItem label="用户名">Vben</VbenDescriptionsItem>
<VbenDescriptionsItem label="状态">
<span style="color: #52c41a">● 正常</span>
</VbenDescriptionsItem>
<VbenDescriptionsItem label="备注" :span="2">
<template #content>
<span style="color: #888">通过 #content 插槽自定义内容</span>
</template>
</VbenDescriptionsItem>
</VbenDescriptions>
</template>API
Descriptions Props
| Prop | Description | Type | Default |
|---|---|---|---|
| items | Data-driven entries; reads the default slot when omitted | DescriptionsItemType[] | - |
| bordered | Whether to show borders | boolean | false |
| column | Columns per row, supports breakpoint config | number | Partial<Record<Breakpoint, number>> | { xs: 1, sm: 2, md: 3, xxxl: 4 } |
| layout | Layout direction | 'horizontal' | 'vertical' | 'horizontal' |
| size | Size | 'small' | 'middle' | 'large' | 'middle' |
| colon | Show colon (only for non-bordered horizontal layout) | boolean | true |
| title | Title | string | - |
| extra | Action area on the right of the title | string | - |
| labelStyle | Shared label style | CSSProperties | - |
| contentStyle | Shared content style | CSSProperties | - |
| class | Custom class for the root node | string | - |
Descriptions Slots
| Slot | Description |
|---|---|
| title | Custom title |
| extra | Custom action area beside the title |
| default | Place VbenDescriptionsItem children |
DescriptionsItem
Each entry in items, or the props of the VbenDescriptionsItem child component.
| Prop | Description | Type | Default |
|---|---|---|---|
| label | Label | string | number | (() => VNode) | Component | - |
| content | Content | string | number | (() => VNode) | Component | - |
| span | Columns to span, 'filled' fills the rest of the row | number | 'filled' | Partial<Record<Breakpoint, number>> | 1 |
| labelStyle | Label style | CSSProperties | - |
| contentStyle | Content style | CSSProperties | - |
| key | Unique key | string | number | - |
DescriptionsItem Slots
Available only for the child component usage.
| Slot | Description |
|---|---|
| default | Content (equivalent to content) |
| content | Custom content |
| label | Custom label |
xingyu4j