---
title: "ContextCards"
description: "A card list of retrieved RAG chunks and their sources."
category: AiContext
status: beta
since: 0.3.9
tags: [rag, context, chunk, source, retrieval]
syncStatus: reviewed
verified: true
---

## Usage

### Basic
Cards fade up in sequence and source chips follow; `staggerStep`, `chipDelay`, and `chipStaggerStep` set the timing.
:::TuffDemoWrapper{demo="ContextCardsContextCardsDemo" code-lang="vue"}
---
code: |
  <template>
    <TxContextCards :chunks="chunks" :total="32" @open="openSource" />
  </template>

  <script setup lang="ts">
  const chunks = [
    {
      id: 'c1',
      title: 'Vendor onboarding rule',
      chars: '290 characters',
      body: 'Cold-chain certification must be verified before a new dairy can be added.',
      source: { name: 'Dairy Onboarding SOP.pdf', badge: 'PDF', tone: 'red', href: 'https://example.com/sop.pdf' },
    },
  ]

  function openSource({ chunk, source }) {
    // The component never navigates; the host decides how to open it.
  }
  </script>
---
:::

### Single Card
`TxContextChunk` renders one card for hosts that lay out their own list; standalone use usually turns `appear` off.

```vue
<TxContextChunk :chunk="chunk" :appear="false" @open="openSource" />
```

### Best Practices

- Pass the corpus size as `total` and the actual hits as `chunks`, so "2 of 32" is visible at a glance.
- Format `chars` host-side, thousands separators included; the component does no number localization.
- Set `appear` to `false` for long lists; past a dozen cards, sequenced entrances feel sluggish.
- Map `tone` to file format consistently (red for PDF, green for CSV), not by card order.

## API Reference

### TxContextCards

#### Props

| Prop | Type | Default | Description |
|------|------|---------|------|
| `chunks` | `ContextChunk[]` | - | The chunk list. |
| `title` | `string` | `'All chunks'` | Header label. |
| `total` | `number \| string` | - | Header count: the corpus size, not `chunks.length`. Omit to drop it. |
| `appear` | `boolean` | `true` | Plays the entrance; turn it off for lists that re-render often. |
| `staggerStep` | `number` | `100` | Gap between card entrances, in ms. |
| `chipDelay` | `number` | `700` | Delay before the first source chip, in ms. |
| `chipStaggerStep` | `number` | `80` | Gap between source chips, in ms. |

#### Events

| Event | Payload | Description |
|------|------|------|
| `open` | `ContextChunkOpenPayload` | Fires when a source row is activated; opening it is the host's call. |

#### Slots

| Slot | Props | Description |
|------|------|------|
| `header` | - | Replaces the header row. |
| `chunk` | `{ chunk, index }` | Replaces a whole card. |
| `chunk-title` / `chunk-body` / `chunk-source` | as in `TxContextChunk` | Forwarded to `TxContextChunk`'s `title` / `body` / `source` slots. |

### TxContextChunk

#### Props

| Prop | Type | Default | Description |
|------|------|---------|------|
| `chunk` | `ContextChunk` | - | A single chunk. |
| `appear` | `boolean` | `true` | Plays the entrance. |
| `enterDelay` | `number` | `0` | Absolute delay before the card fades up, in ms. |
| `chipDelay` | `number` | `700` | Absolute delay before the source chip appears, in ms. |

#### Events

| Event | Payload | Description |
|------|------|------|
| `open` | `ContextChunkOpenPayload` | Fires when the source row is activated. |

#### Slots

| Slot | Props | Description |
|------|------|------|
| `title` | `{ chunk }` | Replaces the title text. |
| `body` | `{ chunk }` | Replaces the body. |
| `source` | `{ chunk, source }` | Replaces the source row. |

### Types

| Name | Description |
|------|------|
| `ContextChunk` | `{ id, title, body?, chars?, source? }`; `chars` is a pre-formatted string such as `290 characters`. |
| `ContextChunkSource` | `{ name, badge?, tone?, href? }`; `tone` reuses `IconChipTone`. |
| `ContextChunkOpenPayload` | `{ chunk, source }`. |

## Overview

- A source with an `href` renders as an `<a>` that keeps it; a click calls `preventDefault()` and emits `open`, matching `TxSources`. Without an `href` it is a static `<span>` with no hover feedback.
- Chunks appended after mount skip the stagger, so they never wait on their index.
- Under reduced motion the delays drop to zero and source chips show at once.
- Entrances play only when an element is created; replaying means remounting (a new `key`).

## Technologies

- The child exports only as `TxContextChunk`, with no unprefixed alias: `ContextChunk` is the data type's name.
- Adapted from [Beautiful UI](https://www.beautifului.dev) (© 2026 Shane Levine, MIT).
- Source: `packages/tuffex/packages/components/src/context-cards/`.

<TuffDocSourceLink />