# Trend Chip

A small pill showing a change, up or down, in seven icon styles.

- Category: Core Elements
- Page: https://wunderui.com/components/trend-chip
- Tier: Free

## Install

```bash
npx wunderui-cli add trend-chip
```

## Import

```tsx
import { TrendChip, TrendCaret, TrendChipIcon } from "@/components/wunderui/trend-chip"
```

## Minimal usage

Then use it:

```tsx
import { TrendChip } from "@/components/ui/trend-chip"

export function RevenueChange() {
  return <TrendChip value="+12.4%" direction="up" />
}
```

Expected result: A small green pill with a rising trend line and +12.4%.

## Usage

```tsx
import { TrendChip } from "@/components/ui/trend-chip"

export function Example() {
  return <TrendChip value="+12.4%" />
}
```

## When to use

### Use Trend Chip for

- The change of a figure in a table cell, a card header or a list row
- A percentage, a number of points or an amount that went up or down since a reference
- A compact pill where the figure itself sits in your own markup

### Use something else

- [Number Value](https://wunderui.com/components/number-value) for a headline figure with its change as one unit
- [Badge](https://wunderui.com/components/badge) for a status or a count, such as Paid or 3 new
- [Meter](https://wunderui.com/components/meter) for a figure measured against a limit, such as storage used

## Behavior

What the chip renders and how it reads.

- **Static:** TrendChip isn't interactive, with no focus, hover state or handlers. Wrap it in your own link or button where the change should open something.
- **Colour follows the sentiment:** By default a rise is green and a fall is red. Positive makes the chip green and negative red whatever the direction, neutral makes it grey, and the glyph always follows the direction, not the colour.
- **Neutral:** A neutral direction shows a minus and, on auto, a grey chip, and the icon choice has no effect on it. Flat is the old name for neutral.
- **Glyphs:** The icon picks one of seven glyphs. For down, the same glyph turns: the trend line mirrors, arrows point down, the triangle rotates 180 degrees and the circled diagonal a quarter turn.
- **Size and spacing:** The pill is 20 px high with 8 px padding on the glyph side. Glyph to label is 4 px for the 12 px glyph, 6 px for 14 px circles and 8 px for 16 px arrows and the triangle.
- **Reading:** A screen reader reads the label as plain text, for example +12.4%. The glyph is hidden and colour isn't announced, so the sign has to be in the string.
- **Numbers:** The label isn't formatted for you. Use English format with a comma, 1,284, and add tabular figures in a column of changing values so the chips keep their width.
- **Motion:** None. The chip appears as it is and doesn't animate when its value, direction or colour changes.
- **Reduced motion:** There is no motion, so reduced motion changes nothing.

## Anatomy

- `TrendChip`: An inline span with a glyph and a label. It isn't interactive and holds no state, so you pass the finished label, the direction and, when colour shouldn't follow direction, the sentiment.
- `Pill`: The rounded surface, 20 px high. Its colour comes from the sentiment: green tint for positive, red for negative, grey for neutral.
- `Glyph`: One of seven icons. The same glyph turns for down and a neutral chip always shows a minus, and the glyph follows the text colour and is hidden from screen readers.
- `Label`: The value text in 12 px semibold. It is the only part a screen reader reads, so it carries the sign and the unit.
- `TrendCaret`: The filled triangle behind the triangle icon, also used by the change label of Number Value. It is exported for your own layouts and is decorative.

## Best practices

### Do

- Write the sign and unit into the value: +12.4%, -3 pts, +$1,204. The glyph is hidden from screen readers, so the label is all they get.
- Keep direction and meaning apart. Direction sets which way the glyph points and sentiment sets the colour: falling churn is down and positive, a rising ticket count is up and negative.
- Choose one icon style per screen and keep it. The padding follows the glyph, so mixed styles in a column don't line up.
- Name what the change is measured against, in the chip (+4.2% vs last month) or in the text beside it. A change without a reference says little.

### Don't

- Don't leave sentiment on auto for a metric where a fall is good. Auto colours by direction, so a falling error rate would show red.
- Don't rely on colour alone. Green and red don't reach everyone, so the sign in the label and the glyph direction say the same thing.
- Don't use it for a status or a count. A chip shows a change, so for a state such as Paid or Failed use Badge.
- Don't use flat as a direction in new code. It is the old name for neutral.

## API reference

### TrendChip

| Prop | Type | Default | Description |
|---|---|---|---|
| value* | string |  | The label of the chip, as a finished string with its sign and unit, for example `+12.4%` or `-1.8 pts`. It is not formatted for you. |
| className | string |  | Extra classes for the pill, for example `tabular-nums` in a column of figures or a different gap. |
| direction | "up" \| "down" \| "neutral" \| "flat" | "up" | Which way the glyph points. `neutral` shows a minus and ignores `icon`; `flat` is the old name for `neutral`. Defaults to `up`. |
| icon | TrendChipIcon | "arrow-diagonal" | The glyph: `trending`, `arrow`, `arrow-diagonal`, `triangle`, `circle-trending`, `circle-diagonal` or `circle-arrow`. The same glyph turns for `down`. Defaults to `arrow-diagonal`. |
| sentiment | "auto" \| "positive" \| "negative" \| "neutral" | "auto" | Whether the change is good or bad, which sets the colour. `auto` colours by direction: up green, down red, neutral grey. Use `positive` for a fall that is good and `negative` for a rise that is bad. It does not change the glyph. Defaults to `auto`. |

### TrendCaret

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string |  | Extra classes for the SVG, for example a colour from the text roles. |
| down | boolean |  | Turns the triangle 180 degrees so it points down. Defaults to false. |
| large | boolean |  | Draws the 14 px caret of Number Value instead of the 16 px caret of the chip. Defaults to false. |

## Examples

### Icon: seven glyphs for the direction

```tsx
import { TrendChip } from "@/components/ui/trend-chip"

export function Example() {
  return (
    <div className="flex items-center gap-3">
      <TrendChip value="+12.4%" />
      <TrendChip value="-3.1%" direction="down" />
    </div>
  )
}
```

### Value: percentage, points, amount, count or a comparison

```tsx
import { TrendChip } from "@/components/ui/trend-chip"

export function Example() {
  return (
    <div className="flex items-center gap-3">
      <TrendChip value="+12.4%" />
      <TrendChip value="-3.1%" direction="down" />
    </div>
  )
}
```

## In context

### KPI cards: four figures with their change

A fall in churn is good, so it points down and stays green. A rise in open tickets points up and is red.

```tsx
import { TrendChip } from "@/components/ui/trend-chip"

const KPIS = [
  { label: "Revenue", value: "$48,200", delta: "+4.2%", direction: "up", sentiment: "auto", caption: "Last 30 days" },
  { label: "Active users", value: "1,284", delta: "+12.6%", direction: "up", sentiment: "auto", caption: "Last 30 days" },
  { label: "Churn rate", value: "2.1%", delta: "-0.4%", direction: "down", sentiment: "positive", caption: "Fewer cancellations" },
  { label: "Open tickets", value: "38", delta: "+6", direction: "up", sentiment: "negative", caption: "Waiting for a reply" },
] as const

export function Example() {
  return (
    <div className="grid w-full grid-cols-[repeat(auto-fit,minmax(200px,1fr))] gap-4">
      {KPIS.map((kpi) => (
        <div key={kpi.label} className="flex flex-col gap-2 rounded-xl border border-border bg-card p-4">
          <span className="text-sm text-text-secondary">{kpi.label}</span>
          <div className="flex items-center gap-2">
            <span className="text-2xl font-semibold tabular-nums text-foreground">{kpi.value}</span>
            <TrendChip value={kpi.delta} direction={kpi.direction} sentiment={kpi.sentiment} />
          </div>
          <span className="text-xs text-text-tertiary">{kpi.caption}</span>
        </div>
      ))}
    </div>
  )
}
```

### Table: a change column beside the figures

The chip sits in a right-aligned cell next to the revenue. A product that did not move reads 0.0% in grey.

```tsx
import { TrendChip } from "@/components/ui/trend-chip"
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table"

const PRODUCTS = [
  { name: "Team plan", revenue: "$18,420", delta: "+9.1%", direction: "up" },
  { name: "Business plan", revenue: "$24,880", delta: "+14.2%", direction: "up" },
  { name: "Extra seats", revenue: "$3,640", delta: "-2.8%", direction: "down" },
  { name: "Support hours", revenue: "$1,260", delta: "0.0%", direction: "neutral" },
] as const

export function Example() {
  return (
    <div className="w-full overflow-hidden rounded-xl border border-border bg-card">
      <Table aria-label="Revenue by product">
        <TableHeader>
          <TableRow>
            <TableHead>Product</TableHead>
            <TableHead className="text-right">Revenue</TableHead>
            <TableHead className="text-right">Change</TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          {PRODUCTS.map((product) => (
            <TableRow key={product.name}>
              <TableCell className="font-medium">{product.name}</TableCell>
              <TableCell className="text-right tabular-nums">{product.revenue}</TableCell>
              <TableCell className="text-right">
                <TrendChip value={product.delta} direction={product.direction} className="tabular-nums" />
              </TableCell>
            </TableRow>
          ))}
        </TableBody>
      </Table>
    </div>
  )
}
```

### Overview: the same metrics for the period you choose

The chips change with the period. The refund rate rises in the shortest period, which is bad, and falls in the longer ones, which is good.

```tsx
import { TrendChip } from "@/components/ui/trend-chip"

const METRICS = [
  { label: "Revenue", value: "$48,200", delta: "+4.2%", direction: "up", sentiment: "auto" },
  { label: "Orders", value: "1,284", delta: "+12.6%", direction: "up", sentiment: "auto" },
  { label: "Refund rate", value: "2.1%", delta: "-0.4%", direction: "down", sentiment: "positive" },
] as const

export function Example() {
  return (
    <ul className="flex w-full flex-col divide-y divide-border rounded-xl border border-border bg-card px-4">
      {METRICS.map((metric) => (
        <li key={metric.label} className="flex items-center justify-between gap-4 py-3">
          <span className="text-sm text-text-secondary">{metric.label}</span>
          <span className="flex items-center gap-3">
            <span className="text-sm font-semibold tabular-nums text-foreground">{metric.value}</span>
            <TrendChip value={metric.delta} direction={metric.direction} sentiment={metric.sentiment} />
          </span>
        </li>
      ))}
    </ul>
  )
}
```

## For AI agents

`get_component("trend-chip")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
