# Record Chip

A link to one record (customer, deal, invoice, person) with its icon or avatar, name and an optional hover preview.

- Category: Data & Tables
- Page: https://wunderui.com/components/record-chip
- Tier: Core and Pro

## Install

Record Chip ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { RecordChip, RecordChipAvatar, RecordChipKnownType, RecordChipProps, RecordChipType } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { RecordChip } from "@wunderui/react"

export function Customer() {
  return <RecordChip type="customer" label="Kestrel Logistics" href="/customers/kestrel-logistics" />
}
```

Expected result: A 28 px chip with a building icon and Kestrel Logistics that links to the customer.

## When to use

### Use Record Chip for

- A reference to a customer, deal, invoice, contract, task, note, file or person in a row, a header or a feed
- The linked records of a record page, such as the customer and contact of a deal
- A record mentioned in a notification or an activity entry, with a preview on hover

### Use something else

- [Badge](https://wunderui.com/components/badge) for a status, a category or a count
- [Context Pill](https://wunderui.com/components/context-pill) for a removable reference in a prompt
- [Avatar](https://wunderui.com/components/avatar) for a person shown by face or initials alone

## Behavior

What the chip renders and how it responds.

- **Element:** With href the chip is an a element, with onClick a button, and with neither a span that takes no focus. A chip with only a preview takes focus, so the card can open from the keyboard.
- **Icon by type:** customer, deal, invoice, contract, task, note, file and person have an icon each, drawn through IconProvider so a Solar or Hugeicons set replaces them. Any other type gets the document icon.
- **Accessible name:** The name, then the type: Kestrel Logistics, customer. typeLabel replaces the type when it is not a word to read out. With a formatted label and labelText, screen readers hear labelText instead of the pieces of the markup.
- **Long names:** The chip never grows past its container. The name truncates with an ellipsis and the full name is the chip's title.
- **Motion:** A press scales the chip to 0.97 on duration-fast; with reduced motion the scale is off and only the colour changes. The preview card fades in from the chip.

## Anatomy

- `RecordChip`: A link with href, a button with onClick, or a plain label without either. It holds no state; you pass the type, the name and what a click should do.
- `Chip`: The bordered surface, 28 px high (24 px at size sm), radius 8. Hover turns it bg-page, a press bg-subtle with a slight scale, and focus shows the indigo border with the 2 px ring.
- `Icon or avatar`: The icon of the type through IconProvider (16 px, 14 px at sm), your own icon, or an avatar with initials or a picture. It is hidden from screen readers.
- `Label`: The record's name. It truncates when the chip runs out of room and the chip's title shows it in full; screen readers hear the type after it.
- `Preview`: A hover card with your summary of the record. It opens on hover and on keyboard focus and grows from the chip.
- `Icon`
- `Label`
- `Record Chip`
- `Remove`

## Best practices

### Do

- Link to the record with href, so it opens in a new tab with the usual keys. Use onClick when the record opens in place, in a sheet or a panel.
- Use size sm in table cells and dense rows, md in headers and forms, and one size per list.
- Keep the preview short: three or four facts that help decide whether to open the record.
- Pass typeLabel when the type is an id rather than a word, so screen readers hear support ticket instead of ticket_v2.
- For an attached or removable record use onRemove; do not build a second button beside the chip.

### Don't

- Don't use it for a status or a category. A record chip points to something you can open; for Paid or Overdue use Badge.
- Don't put the only way to reach a record in the preview card. The card is a summary; the chip itself is the link.
- Don't add a remove button. For a removable reference in a prompt or a filter use Context Pill or a chip of Badge.

## API reference

### RecordChip

| Prop | Type | Default | Description |
|---|---|---|---|
| label* | ReactNode |  | The record's name. Truncates when there is no room; the full name is the title. Formatted content works too, such as a search match in a `<mark>`: then pass `labelText`. |
| type* | RecordChipType |  | The kind of record: `customer`, `deal`, `invoice`, `contract`, `task`, `note`, `file`, `person` or any other string. Sets the icon and is read out after the name. |
| avatar | RecordChipAvatar \| ReactElement |  | A picture instead of the icon: `{ src, initials, color }`, or your own Avatar element as tall as the text. |
| className | string |  | Extra classes on the chip. |
| href | string |  | Makes the chip a link to the record. |
| icon | ReactNode |  | Replaces the icon of the type. |
| labelText | string |  | The plain name, for the title, the accessible name and the avatar initials when `label` is not a string. Defaults to `label` when it is a string. |
| onClick | (event) => void |  | Makes the chip a button when there is no `href`, for example to open the record in a sheet. |
| onRemove | () => void |  | Shows a × at the end of the chip (an attached record in a composer, a filter). It is its own button beside the chip's link or button ("Remove <name>"), so it never opens the record. |
| preview | ReactNode |  | A hover card with a summary of the record; it also opens on keyboard focus. |
| size | "sm" \| "md" | "md" | `sm` is 24 px for table cells and dense rows, `md` 28 px. Defaults to `md`. |
| typeLabel | string |  | What screen readers hear for the type, when the type string is not a word. Defaults to the type. |

## Examples

### Type: eight record types, each with its icon

### Action: link, button, hover preview or a plain label

## In context

### Deal: what a record links to

A deal lists its customer, contact, contract, invoice and next task as small chips, so each one is a click away.

### Search results: the match highlighted in the name

The label takes formatted content, here the search match in a mark. labelText keeps the title and the name screen readers hear plain.

### Removable: a record attached to a message

`onRemove` adds a × at the end of the chip. It is its own button ("Remove Kestrel Logistics") beside the chip's link or button, so removing never opens the record.

## For AI agents

`get_component("record-chip")`

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