CardItem | Tuff Docs

Usage

Use the right slot for switches, chevrons, metadata, or secondary status. The row itself does not emit clicks unless clickable is enabled.

Loading demo...

Set clickable=true only when the row itself performs an action. If only the right slot is interactive, keep the row non-clickable.
Override --tx-card-item-hover-bg when the rows sit on a dark, translucent surface. The default washes --tx-bg-color-overlay at 18%, and under the dark theme that token is #1d1e1f itself — a dark wash on a dark panel, which reads as no hover at all. Point it at a semantic surface colour of the host rather than fighting the component's rule with :deep.
Pass an explicit role when a clickable row is not already inside a semantic list or menu.
Use avatar slot for complex media. Use avatarUrl, iconClass, or avatarText for simple, generated media.
Keep the right slot compact; long controls can collapse the title area.
Avoid duplicating row navigation and switch toggles on the same click target. Separate row click behavior from right-slot controls.

Prop	Type	Default	Description
`role`	`string`	`undefined`	ARIA role applied only when `clickable=true`. Pass `button`, `menuitem`, or `option` when the row needs explicit semantics.
`title`	`string`	`''`	Primary single-line label when the `title` slot is not used.
`subtitle`	`string`	`''`	Secondary single-line label below the title.
`description`	`string`	`''`	Supporting copy rendered below the top row.
`iconClass`	`string`	`''`	Icon class rendered in the avatar area when no avatar URL is provided.
`avatarText`	`string`	`''`	Text fallback rendered in the avatar area when no image or icon is provided.
`avatarUrl`	`string`	`''`	Image URL rendered before icon or text avatar fallbacks.
`avatarSize`	`number`	`36`	Avatar box size in pixels.
`avatarShape`	`'circle' \| 'rounded'`	`'circle'`	Avatar corner style. `rounded` uses a 12px radius.
`clickable`	`boolean`	`false`	Enables pointer cursor, focusability, and mouse / Enter activation.
`active`	`boolean`	`false`	Applies the selected visual state.
`disabled`	`boolean`	`false`	Disables focus and click / keyboard activation.

Slot	Props	Description
`avatar`	-	Replaces the generated image / icon / text avatar area.
`title`	-	Replaces the primary title content.
`subtitle`	-	Replaces the subtitle content.
`description`	-	Replaces the supporting description content.
`right`	-	Renders actions or trailing metadata on the right side of the top row.

Event	Payload	Description
`click`	`MouseEvent`	Emitted on mouse click when `clickable=true` and not disabled. Enter activation uses the same event channel at runtime.

align="center" puts the row's columns on one centre line, which is what a single-line list row wants: a taller leading column — a caret, a checkbox, an avatar — otherwise pins the label to the top of the row. The default stays start, because a card whose text wraps to several lines should align with the top of its media column.
The left media column is omitted when there is no avatar slot, avatarUrl, iconClass, or avatarText.
Generated avatar priority is avatarUrl first, then iconClass, then avatarText.
tabindex="0" is applied only when clickable=true and disabled=false.
role is also applied only when clickable=true; there is no implicit default role.
disabled=true adds the disabled class, removes focusability, and suppresses mouse and Enter activation.
The hover fill reads --tx-card-item-hover-bg and the active fill reads --tx-card-item-active-bg. Their defaults are 18% of --tx-bg-color-overlay and 8% of --tx-color-primary, so an unset row renders pixel for pixel what it did before. Border colours are not overridable and still come from --tx-border-color-light / --tx-color-primary.
Text areas use single-line ellipsis for title and subtitle; description can wrap.
Hovering an active row deepens its accent rather than replacing it with the neutral hover fill: the hover rule outranks the active rule on its own, so a selected row used to lose its highlight under the pointer.

Reviewed against packages/tuffex/packages/components/src/card-item/src/TxCardItem.vue, types.ts, and card-item.test.ts.
Verified coverage: card-item.test.ts covers text and icon rendering, avatar CSS variables, image-over-icon/text priority, named slots, clickable mouse/Enter emits, disabled blocking, the no-left layout, and that the two overridable surface variables still fall back to their original formulas.
Accessibility note: a clickable row gets focusability but no implicit role. Supply the semantic role that matches the surrounding interaction pattern, and keep interactive controls in right outside the row click target.
Component source: packages/tuffex/packages/components/src/card-item/src/TxCardItem.vue.
Types: packages/tuffex/packages/components/src/card-item/src/types.ts exports CardItemProps and CardItemAvatarShape.
Coverage: packages/tuffex/packages/components/src/card-item/__tests__/card-item.test.ts verifies generated media, slots, keyboard activation, disabled state, and layout fallbacks.
查看源码
packages/tuffex/packages/components/src/card-item/index.ts