Skip to content
WunderUI

Record Chip

Pro

A reference to one record, such as a customer, deal, invoice or person: its icon or avatar and its name, as a link, a button or a label.

Playground

Installation

Record Chip comes with WunderUI Core and Pro, in the package from your plan. See the plans.

Then import what you need:

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

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 for

  • Badge for a status, a category or a count
  • Context Pill for a removable reference in a prompt
  • Avatar for a person shown by face or initials alone

Type

The type picks the icon: customer, deal, invoice, contract, task, note, file and person. Any other string works too and gets the document icon; pass icon for your own. A person or company can show an avatar instead, initials on a tint or a picture. Screen readers hear the name and then the type.

Action

With href the chip is a link to the record, with onClick a button, for example to open the record in a sheet. preview adds a hover card with a summary that also opens on keyboard focus. Without any of them the chip is a label and takes no focus. A long name truncates and the chip's title shows it in full. The label can be formatted content, such as a search match in a mark; then labelText gives the plain name for the title, screen readers and the initials.

Behavior and motion

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

The figure shows a customer chip at size md, enlarged. A person shows initials on a tint instead of the icon.

  • data-slot="record-chip-removable"

    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.

  • 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.

  • 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.

  • 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.

  • data-slot="record-chip-preview"Optional

    A hover card with your summary of the record. It opens on hover and on keyboard focus and grows from the chip.

  • data-slot="record-chip-icon"Optional
  • data-slot="record-chip-label"
  • data-slot="record-chip"
  • data-slot="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.

  • Do

    Use size sm in table cells and dense rows, md in headers and forms, and one size per list.

  • Do

    Keep the preview short: three or four facts that help decide whether to open the record.

  • Do

    Pass typeLabel when the type is an id rather than a word, so screen readers hear support ticket instead of ticket_v2.

  • 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

    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

    Don't add a remove button. For a removable reference in a prompt or a filter use Context Pill or a chip of Badge.

  • Do

    For an attached or removable record use onRemove; do not build a second button beside the chip.

API reference

RecordChip is one component, so this table lists every prop.

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.

PropTypeDefaultDescription
type requiredRecordChipType—The kind of record: , , , , , , , or any other string. Sets the icon and is read out after the name.
label requiredReactNode—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 : then pass .
hrefstring—Makes the chip a link to the record.
onClick(event) => void—Makes the chip a button when there is no , for example to open the record in a sheet.
previewReactNode—A hover card with a summary of the record; it also opens on keyboard focus.
size"sm" | "md""md" is 24 px for table cells and dense rows, 28 px. Defaults to .
iconReactNode—Replaces the icon of the type.
avatarRecordChipAvatar | ReactElement—A picture instead of the icon: , or your own Avatar element as tall as the text.
labelTextstring—The plain name, for the title, the accessible name and the avatar initials when is not a string. Defaults to when it is a string.
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.
typeLabelstring—What screen readers hear for the type, when the type string is not a word. Defaults to the type.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("record-chip")
InstallIncluded in Core and Pro

The full library index for assistants is at /llms.txt.