---
title: "CardItem"
description: "A compact list row with avatar, text, and trailing actions."
category: Layout
status: beta
since: 0.3.4
tags: [card, list, settings]
syncStatus: reviewed
verified: true
---

## Usage

### Basic
Put switches, chevrons, or metadata in the `right` slot; the row emits no clicks unless `clickable` is set.
::::TuffDemoWrapper{demo="CardItemCardItemDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  import { ref } from 'vue'

  const enabled = ref(true)
  </script>

  <template>
    <TxCardItem title="Enable sync" description="The right slot can combine controls." icon-class="i-carbon-settings">
      <template #right>
        <TxSwitch v-model="enabled" />
        <i class="i-carbon-chevron-right" />
      </template>
    </TxCardItem>
  </template>
---
::::

### Best Practices

- Set `clickable` only when the row itself performs an action; if only the `right` slot is interactive, keep the row non-clickable.
- Pass a `role` (`button`, `menuitem`, or `option`) when a clickable row isn't inside a semantic list or menu.
- Use `avatarUrl`, `iconClass`, or `avatarText` for simple media and the `avatar` slot for complex media.
- Keep the `right` slot compact; long controls squeeze the title.
- On a dark, translucent panel, point `--tx-card-item-hover-bg` at the host's surface color instead of overriding the rule with `:deep`.

## API Reference

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `role` | `string` | `undefined` | ARIA role on the root; there is no default. |
| `title` | `string` | `''` | Primary label, truncated to one line. |
| `subtitle` | `string` | `''` | Secondary label below the title, truncated to one line. |
| `description` | `string` | `''` | Supporting text below the top row; wraps. |
| `iconClass` | `string` | `''` | Icon class for the avatar area. |
| `avatarText` | `string` | `''` | Text for the avatar area. |
| `avatarUrl` | `string` | `''` | Avatar image; takes priority over icon and text. |
| `avatarSize` | `number` | `36` | Avatar size in px. |
| `avatarShape` | `'circle' \| 'rounded'` | `'circle'` | Avatar shape; `rounded` uses a 12px radius. |
| `clickable` | `boolean` | `false` | Enables the pointer cursor, focus, and click / Enter / Space activation. |
| `active` | `boolean` | `false` | Selected state. |
| `disabled` | `boolean` | `false` | Blocks focus and activation, and sets `aria-disabled`. |
| `tabindex` | `number` | `undefined` | Overrides the automatic tab stop (`0` when clickable); listbox hosts pass `-1`. |
| `align` | `'start' \| 'center'` | `'start'` | Cross-axis alignment of the columns; use `center` for single-line rows. |

### Events

| Event | Payload | Description |
|------|---------|-------------|
| `click` | `MouseEvent` | Fires on click, Enter, or Space when the row is clickable and not disabled. |

### Slots

| Slot | Props | Description |
|------|-------|-------------|
| `avatar` | - | Replaces the generated avatar. |
| `title` | - | Replaces the title. |
| `subtitle` | - | Replaces the subtitle. |
| `description` | - | Replaces the description. |
| `right` | - | Actions or metadata at the right of the top row. |

## Overview

- Without an `avatar` slot, `avatarUrl`, `iconClass`, or `avatarText`, the left media column is omitted.
- A clickable, enabled row gets `tabindex="0"`; there is no implicit `role`.
- Only Enter / Space on the row itself activate it; key presses in `right`-slot controls pass through.
- Hovering an active row deepens its accent instead of swapping in the neutral hover fill.
- Hover and active fills read `--tx-card-item-hover-bg` / `--tx-card-item-active-bg`, defaulting to 18% of `--tx-bg-color-overlay` and 8% of `--tx-color-primary`; border colors aren't overridable.

## Technologies

- Source: `packages/tuffex/packages/components/src/card-item/`.

<TuffDocSourceLink />