# DataTrend

A metric block with a label, current value and change. An optional metric icon and comparison text provide context. Trend sets the tone automatically: up is success, down is danger and flat is neutral.

## Usage

### When to use

- Show a current metric and its change against another period.
- Show increases, decreases and unchanged values with automatic direction colors.

### When not to use

- Read-only facts without a change comparison. Use Metadata.
- A short categorical status. Use Badge.
- Progress toward a known total. Use Progress.

## Variants

### trend

Direction of the change. Sets the tone automatically: up uses success, down uses danger and flat uses neutral. There is no tone override.

Values: `up`, `down`, `flat`. Default: `undefined`.

### size

Current value size: heading 3, heading 2 or heading 1. This static display does not use control heights.

Values: `sm`, `md`, `lg`. Default: `md`.

## Examples

### Revenue

Sample data. An optional metric icon appears before the label.

```tsx
<DataTrend label="Revenue" value="$24,800" leadingIcon={<IconChartLine size={16} />} trend="up" change="12.5%" comparison="vs. previous month" />
```

### Directions

Sample data. Direction sets success, danger or neutral automatically.

```tsx
<div className="grid w-full gap-xl sm:grid-cols-3">
  <DataTrend label="Revenue" value="$24,800" trend="up" change="12.5%" />
  <DataTrend label="Active users" value="1,240" trend="down" change="4.2%" />
  <DataTrend label="Subscribers" value="480" trend="flat" change="0%" />
</div>
```

### Fewer active users

Sample data. A decrease automatically uses the danger tone.

```tsx
<DataTrend label="Active users" value="1,240" trend="down" change="8.2%" comparison="vs. previous month" />
```

### Absolute change

Sample data. Changes can use an absolute count instead of a percentage.

```tsx
<DataTrend label="Requests" value="12,400" trend="up" change="240" comparison="vs. previous week" />
```

### Percentage points

Sample data. A rate can change in percentage points.

```tsx
<DataTrend label="Conversion rate" value="32.1%" trend="up" change="2.4 pts" comparison="vs. previous month" />
```

### Inside a card

Sample data. Card owns padding, surface and border.

```tsx
<Card className="w-full max-w-sm">
  <CardContent>
    <DataTrend label="Revenue" value="$24,800" leadingIcon={<IconChartLine size={16} />} trend="up" change="12.5%" comparison="vs. previous month" />
  </CardContent>
</Card>
```

### Inside a table

Sample data. Compact metric blocks sit in table cells.

```tsx
<Table className="max-w-full [&_th]:whitespace-normal [&_th]:wrap-anywhere [&_td]:wrap-anywhere [&_th]:px-sm [&_td]:px-sm">
  <TableCaption>Sample team activity, compared with the previous week.</TableCaption>
  <TableHeader>
    <TableRow>
      <TableHead>Team</TableHead>
      <TableHead>Activity</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>Design</TableCell>
      <TableCell>
        <DataTrend label="Active members" value="24" trend="up" change="3" size="sm" />
      </TableCell>
    </TableRow>
    <TableRow>
      <TableCell>Engineering</TableCell>
      <TableCell>
        <DataTrend label="Active members" value="48" trend="down" change="2" size="sm" />
      </TableCell>
    </TableRow>
  </TableBody>
</Table>
```

### Custom direction labels

Sample data. Localize direction text independently of number formatting.

```tsx
<DataTrend label="Revenue" value="$24,800" trend="down" change="8.2%" trendLabels={{ up: "Rose by", down: "Fell by", flat: "Unchanged" }} comparison="vs. previous month" />
```

## Do and don't

### Do

- Use a short metric label and include units in formatted values.
- Set trend to up, down or flat; its color follows automatically.
- Include a comparison period so the change has context.
- Compose inside Card when a surface is needed, or in a table cell.
- Keep existing values visible while refreshing data; use Skeleton only for first load.

### Don't

- Do not override the trend color or add a separate tone control.
- Do not use chart series colors for the change indicator.
- Do not pass interactive content as a decorative metric icon.
- Do not give every static metric a live-region role.
- Do not add a nested Card or hardcoded colors through className.

## Props

| Name | Type | Values | Default | Description |
| --- | --- | --- | --- | --- |
| `label` (required) | `string` |  |  | Name of the metric. |
| `value` (required) | `string \| number` |  |  | Current value, formatted by the caller with its currency, unit and locale. |
| `leadingIcon` | `node` |  |  | Optional decorative icon before the metric label. Pass an outline icon with size={16}. |
| `trend` (required) | `enum` | `up`, `down`, `flat` |  | Direction of the change. Sets the tone automatically: up uses success, down uses danger and flat uses neutral. There is no tone override. |
| `change` (required) | `string \| number` |  |  | Formatted magnitude, such as 12.5%, 2.4 pts or 240. The direction icon and accessible text express its direction. |
| `comparison` | `string` |  |  | Optional comparison period, such as vs. previous month. |
| `size` | `enum` | `sm`, `md`, `lg` | `md` | Current value size: heading 3, heading 2 or heading 1. This static display does not use control heights. |
| `trendLabels` | `Partial<DataTrendLabels>` |  |  | Accessible direction text: up, down and flat. Defaults: Increased by, Decreased by and No change. Override entries for your locale. |

## Anatomy

| Part | Description |
| --- | --- |
| `root` | Metric stack without a card surface, border or shadow. |
| `label` | Metric name beside the optional icon. |
| `icon` | Optional decorative leading metric icon, 16px. |
| `value` | Current value with tabular numerals and wrapping for long values. |
| `content` | Direction icon, accessible direction text and formatted change. |
| `glyph` | Decorative built-in direction icon, 16px. |
| `description` | Optional comparison period, wrapping on narrow surfaces. |

## Accessibility

Role: `generic`

- The label, value, accessible direction, change and comparison remain text in reading order.
- Icons are decorative. The arrow shape and hidden direction text convey the same direction as the automatic color, without relying on color alone.
- No live-region role is added by default. Add role="status" only when updates need announcements.
- Callers format values and changes for their locale and localize trendLabels.
- Native div attributes and className pass through to the root. Interactive content does not belong in leadingIcon.

## Install

```bash
npx werewolf-ui add data-trend
```

Run `npx werewolf-ui init` once in your app before adding components. Init sets up tokens, their CSS import and agent rules. Add installs this component and its dependencies while preserving your theme. See [Installation](https://werewolf-ui.vercel.app/docs/installation.md) for requirements and the alternative registry setup.