Descriptions | Tuff Docs

Installation

pnpm add @talex-touch/tuffex

import { TxDescriptions, TxDescriptionsItem } from '@talex-touch/tuffex/descriptions'
// One sheet for both components
import '@talex-touch/tuffex/descriptions/style.css'
import '@talex-touch/tuffex/base.css' // tokens + resets, once per app

Usage

Basic

Two columns by default; an empty value shows emptyText, while 0 shows as a value.

Loading demo...

Layout and Size

layout puts each label beside or above its value; size="sm" suits drawers and side panels.

Loading demo...

Columns and Span

span widens a long field up to columns; below 480px of container the list falls back to one column.

Loading demo...

Best Practices

Leave a missing value empty instead of writing —; pass emptyText once for a different placeholder.
Give a long field (an ID, an address, a note) a span rather than lowering columns for the whole list.
Keep labels short; set labelWidth when stacked lists on one page must line up.
Put items directly in the default slot (v-for and v-if are fine); don't wrap them.
Let the parent give the list its width: flex: 1 in a flex row. A shrink-to-fit parent collapses it.

API Reference

TxDescriptions

Props

Name	Type	Default	Description
`columns`	`number`	`2`	Items per row, floored, at least 1.
`layout`	`'horizontal' \| 'vertical'`	`'horizontal'`	`horizontal`: labels beside values, sharing a track per column. `vertical`: labels above values.
`size`	`'sm' \| 'md'`	`'md'`	`md`: 14px values, 13px labels. `sm`: 13px for both, with tighter gaps.
`emptyText`	`string`	`'—'`	Placeholder for a value that renders nothing; `0` is a value.
`labelWidth`	`string \| number`	-	Label-track width in the horizontal layout, px for numbers; defaults to the longest label, up to 40%.

Slots

Slot	Description
`default`	The `TxDescriptionsItem`s, directly; a wrapping element breaks the `<dl>` and the grid.

TxDescriptionsItem

Props

Name	Type	Default	Description
`label`	`string`	`''`	Label text; the `label` slot replaces it.
`span`	`number`	`1`	Columns to span, clamped between 1 and `columns`.

Slots

Slot	Description
`default`	The value; `emptyText` shows when it renders nothing.
`label`	Replaces the label text, inside the same `<dt>`.

CSS Variables

Variable	Default	Description
`--tx-descriptions-gap`	`12px`; `sm` `8px`	Row gap, and the label-to-value gap in the horizontal layout; pairs sit twice this apart.
`--tx-descriptions-font-size`	`14px`; `sm` `13px`	Value size; labels are 1px smaller, never under 13px.
`--tx-descriptions-label-width`	unset	Label-track width; `labelWidth` writes it on the root, and hosts may set it on an ancestor.

sm sets the first two at one class's weight, so any heavier host rule (a scoped class counts) overrides them.
The component writes --tx-descriptions-columns and --tx-descriptions-span itself; hosts don't set them.

Types

type DescriptionsLayout = 'horizontal' | 'vertical'
type DescriptionsSize = 'sm' | 'md'

Overview

Each item is a div group inside a <dl> holding one dt and one dd, read as a term and its description.
In the horizontal layout, a column's labels share one track, as wide as the longest label up to 40%, then wrap; values align with the label's first baseline.
Items fill rows in source order; an item that doesn't fit the rest of a row starts the next, leaving a gap.
Below 480px of its own width (a container query, not the viewport) the list is one column and every item spans the row.
A slot that renders only comments or whitespace ({{ null }}, a false v-if, an empty v-for) is empty and shows emptyText; 0 and any element are content.
Values wrap anywhere, so a long ID, email, or URL never widens its column.

Technologies

CSS subgrid aligns the labels; @container (width < 480px) on the root drives the one-column fallback, so the list is a separate element inside the root.
Source: packages/tuffex/packages/components/src/descriptions/.

查看源码

packages/tuffex/packages/components/src/descriptions/index.ts

Use cases

The fields of one record in a drawer or detail panel: a member, a subscription, a run, a plugin.
A summary above a form or table, naming what the next step acts on.
Read-only settings and metadata inside a card.

DataTable: many records with the same fields.
Form: the editable counterpart, label and field in a row.
Drawer: the usual host for one record's details.