Chips

Web/Mobile

A row of selectable pills for filtering, tagging, or picking one or more options.

"use client"

import { Chip, Chips } from "@/components/cubix/chips"

const categories = [
  { value: "electronics", label: "لوازم دیجیتال" },
  { value: "fashion", label: "پوشاک" },
  { value: "home", label: "خانه و آشپزخانه" },
  { value: "beauty", label: "زیبایی و سلامت" },
  { value: "books", label: "کتاب" },
]

export function ChipsDemo() {
  return (
    <Chips defaultValue={["fashion"]} className="w-fit max-w-md justify-center">
      {categories.map((category) => (
        <Chip key={category.value} value={category.value}>
          {category.label}
        </Chip>
      ))}
    </Chips>
  )
}

Installation

pnpm dlx cubix-ui@latest add chips --base aria

Usage

Import

import { Chip, Chips } from "@/components/cubix/chips"

const categories = [
  { value: "electronics", label: "لوازم دیجیتال" },
  { value: "fashion", label: "پوشاک" },
  { value: "home", label: "خانه و آشپزخانه" },
  { value: "beauty", label: "زیبایی و سلامت" },
  { value: "books", label: "کتاب" },
]

Example

<Chips defaultValue={["fashion"]} className="w-fit max-w-md justify-center">
  {categories.map((category) => (
    <Chip key={category.value} value={category.value}>
      {category.label}
    </Chip>
  ))}
</Chips>

Composition

Every Chip is a toggle inside a Chips group. Selection is tracked by value, the same string each chip passes. Pass icon or avatar for a leading visual, and onRemove for a remove button.

Structure

Chips
└── Chip
    ├── icon | avatar
    └── remove button (with onRemove)

Accessibility

Each chip is a toggle button that reports its state with aria-pressed. The group is a single tab stop; arrow keys move between chips and follow the reading direction, so they are mirrored in RTL. Removable chips are removed with Backspace or Delete, and focus moves to the neighboring chip. Give the remove button a specific name with removeLabel.

Key	Action
Enter / Space	Toggle the focused chip.
Tab / Shift + Tab	Move to the next or previous focusable element on the page.
ArrowLeft / ArrowRight	Move focus to the next or previous enabled chip in reading direction, so the keys are mirrored in RTL.
Home / End	Move focus to the first or last enabled chip.
Backspace / Delete	Remove the focused chip when it has onRemove. Focus moves to the next chip, or the previous one at the end.

Examples

Multiple

Set multiple to select any number of chips. Pass every selected value to defaultValue.

"use client"

import { Chip, Chips } from "@/components/cubix/chips"

const skills = [
  { value: "design", label: "طراحی" },
  { value: "frontend", label: "فرانت‌اند" },
  { value: "backend", label: "بک‌اند" },
  { value: "devops", label: "دواپس" },
]

export function ChipsMultipleDemo() {
  return (
    <Chips multiple defaultValue={["design", "frontend"]} className="w-fit justify-center">
      {skills.map((skill) => (
        <Chip key={skill.value} value={skill.value}>
          {skill.label}
        </Chip>
      ))}
    </Chips>
  )
}

Controlled

Pass value and onValueChange to own the selected chips, for example to read or set the selection from outside.

انتخاب‌شده: طراحی

"use client"

import * as React from "react"

import { Chip, Chips } from "@/components/cubix/chips"

const skills = [
  { value: "design", label: "طراحی" },
  { value: "frontend", label: "فرانت‌اند" },
  { value: "backend", label: "بک‌اند" },
]

export function ChipsControlledDemo() {
  const [value, setValue] = React.useState<string[]>(["design"])
  const selectedLabels = skills
    .filter((skill) => value.includes(skill.value))
    .map((skill) => skill.label)

  return (
    <div className="flex flex-col items-center gap-4">
      <Chips multiple value={value} onValueChange={setValue} className="w-fit justify-center">
        {skills.map((skill) => (
          <Chip key={skill.value} value={skill.value}>
            {skill.label}
          </Chip>
        ))}
      </Chips>
      <p aria-live="polite" className="text-caption text-muted-foreground">
        انتخاب‌شده: {selectedLabels.length ? selectedLabels.join("، ") : "هیچ‌کدام"}
      </p>
    </div>
  )
}

Variants

Set variant on a Chip to pick how it looks when selected, using the same colors as Button. Unselected chips stay outlined.

"use client"

import { Chip, Chips } from "@/components/cubix/chips"

const variants = [
  { value: "default", label: "پیش‌فرض" },
  { value: "secondary", label: "ثانویه" },
  { value: "gray", label: "خاکستری" },
  { value: "outline", label: "خط‌دار" },
] as const

export function ChipsVariantsDemo() {
  return (
    <Chips
      multiple
      defaultValue={variants.map((variant) => variant.value)}
      className="w-fit justify-center"
    >
      {variants.map((variant) => (
        <Chip
          key={variant.value}
          value={variant.value}
          variant={variant.value}
          icon={<Icon />}
        >
          {variant.label}
        </Chip>
      ))}
    </Chips>
  )
}

Sizes

Set size on a Chip to use the same heights as Button. The default is sm.

"use client"

import { Chip, Chips } from "@/components/cubix/chips"

const sizes = [
  { value: "xs", label: "خیلی کوچک" },
  { value: "sm", label: "کوچک" },
  { value: "default", label: "پیش‌فرض" },
  { value: "lg", label: "بزرگ" },
] as const

export function ChipsSizesDemo() {
  return (
    <Chips multiple defaultValue={sizes.map((size) => size.value)} className="w-fit justify-center">
      {sizes.map((size) => (
        <Chip key={size.value} value={size.value} size={size.value} icon={<Icon />}>
          {size.label}
        </Chip>
      ))}
    </Chips>
  )
}

With icon

Pass icon to show an icon at the inline start, hidden from assistive technology.

"use client"

import { Chip, Chips } from "@/components/cubix/chips"

const skills = [
  { value: "design", label: "طراحی", icon: <Icon /> },
  { value: "frontend", label: "فرانت‌اند", icon: <Icon /> },
  { value: "backend", label: "بک‌اند", icon: <Icon /> },
]

export function ChipsIconDemo() {
  return (
    <Chips defaultValue={["design"]} className="w-fit justify-center">
      {skills.map((skill) => (
        <Chip key={skill.value} value={skill.value} icon={skill.icon}>
          {skill.label}
        </Chip>
      ))}
    </Chips>
  )
}

Removable

Pass onRemove to show a remove button. Remove the chip from your list and from the selection in the same handler.

"use client"

import * as React from "react"

import { Button } from "@/components/cubix/button"
import { Chip, Chips } from "@/components/cubix/chips"

const initialTags = [
  { value: "react", label: "ری‌اکت" },
  { value: "typescript", label: "تایپ‌اسکریپت" },
  { value: "tailwind", label: "تیلویند" },
  { value: "accessibility", label: "دسترس‌پذیری" },
]

export function ChipsRemovableDemo() {
  const [tags, setTags] = React.useState(initialTags)
  const [selected, setSelected] = React.useState<string[]>(["react"])

  function removeTag(value: string) {
    setTags((current) => current.filter((tag) => tag.value !== value))
    setSelected((current) => current.filter((item) => item !== value))
  }

  if (tags.length === 0) {
    return (
      <div className="flex items-center gap-2 text-caption text-muted-foreground">
        همه برچسب‌ها حذف شدند.
        <Button
          variant="link"
          size="sm"
          className="h-auto px-0"
          onClick={() => setTags(initialTags)}
        >
          بازگردانی
        </Button>
      </div>
    )
  }

  return (
    <Chips
      multiple
      value={selected}
      onValueChange={setSelected}
      className="w-fit max-w-md justify-center"
    >
      {tags.map((tag) => (
        <Chip
          key={tag.value}
          value={tag.value}
          removeLabel={`حذف ${tag.label}`}
          onRemove={() => removeTag(tag.value)}
        >
          {tag.label}
        </Chip>
      ))}
    </Chips>
  )
}

Avatar

Pass an Avatar to avatar to show it in place of the icon. It scales with size.

"use client"

import * as React from "react"

import { Avatar, AvatarFallback, AvatarImage } from "@/components/cubix/avatar"
import { Chip, Chips } from "@/components/cubix/chips"

const initialPeople = [
  { value: "maryam", label: "مریم کریمی", src: "/docs/avatar/girl.jpg", initial: "م" },
  { value: "reza", label: "رضا احمدی", initial: "ر" },
  { value: "ali", label: "علی رضایی", initial: "ع" },
]

export function ChipsAvatarDemo() {
  const [people, setPeople] = React.useState(initialPeople)
  const [selected, setSelected] = React.useState<string[]>(["maryam"])

  function removePerson(value: string) {
    setPeople((current) => current.filter((person) => person.value !== value))
    setSelected((current) => current.filter((item) => item !== value))
  }

  return (
    <Chips multiple value={selected} onValueChange={setSelected} className="w-fit justify-center">
      {people.map((person) => (
        <Chip
          key={person.value}
          value={person.value}
          variant="gray"
          avatar={
            <Avatar>
              {person.src ? <AvatarImage src={person.src} alt="" /> : null}
              <AvatarFallback>{person.initial}</AvatarFallback>
            </Avatar>
          }
          removeLabel={`حذف ${person.label}`}
          onRemove={() => removePerson(person.value)}
        >
          {person.label}
        </Chip>
      ))}
    </Chips>
  )
}

Disabled item

Set disabled on a Chip to keep it visible but locked. Arrow key navigation skips it.

"use client"

import { Chip, Chips } from "@/components/cubix/chips"

const categories = [
  { value: "electronics", label: "لوازم دیجیتال" },
  { value: "fashion", label: "پوشاک" },
  { value: "books", label: "کتاب", disabled: true },
]

export function ChipsDisabledItemDemo() {
  return (
    <Chips defaultValue={["fashion"]} className="w-fit justify-center">
      {categories.map((category) => (
        <Chip key={category.value} value={category.value} disabled={category.disabled}>
          {category.label}
        </Chip>
      ))}
    </Chips>
  )
}

Disabled

Set disabled on Chips to lock every chip in its current state.

"use client"

import { Chip, Chips } from "@/components/cubix/chips"

const categories = [
  { value: "electronics", label: "لوازم دیجیتال" },
  { value: "fashion", label: "پوشاک" },
  { value: "home", label: "خانه و آشپزخانه" },
]

export function ChipsDisabledDemo() {
  return (
    <Chips disabled defaultValue={["fashion"]} className="w-fit justify-center">
      {categories.map((category) => (
        <Chip key={category.value} value={category.value}>
          {category.label}
        </Chip>
      ))}
    </Chips>
  )
}

API Reference

Note: Parts render data-slot attributes (chips, chip, chip-root, chip-icon, chip-avatar, chip-remove) for targeting in tests and parent selectors. Use the same props on Base UI, React Aria, and Radix.

Chips

Prop	Type	Default	Description
multiple	boolean	false	Keep more than one chip selected. Without it, selecting a chip deselects the selected one, and the selected chip deselects itself.
value	string[]	-	Controlled selected chips. Use an array in both modes and pass at most one value in single mode.
defaultValue	string[]	-	Chips selected on first render when uncontrolled.
onValueChange	(value: string[]) => void	-	Called with the selected chips whenever a chip is toggled.
disabled	boolean	false	Disable every chip in the group.
dir	"ltr" \| "rtl"	-	Text direction of the group. Defaults to the closest dir on the page.
lang	string	-	Language of the group. Defaults to the closest lang on the page.
className	string	-	Additional Tailwind classes merged with the root styles (last one wins).

Chip

Prop	Type	Default	Description
value	string	-	Unique value used in value, defaultValue and onValueChange. Required.
icon	ReactNode	-	Icon rendered at the inline start, before the label, and hidden from assistive technology.
avatar	ReactNode	-	Avatar rendered at the inline start in place of the icon, sized to the chip.
variant	"default" \| "secondary" \| "gray" \| "outline"	"default"	How the chip looks when selected, matching the Button variant of the same name.
size	"xs" \| "sm" \| "default" \| "lg"	"sm"	Chip height, matching the Button size of the same name: 28, 32, 40 or 48px.
onRemove	() => void	-	Renders a remove button at the inline end and lets Backspace or Delete remove the focused chip. Removing does not change selection; update the value yourself.
removeLabel	string	"حذف"	Accessible name of the remove button. Include the chip label, for example حذف ری‌اکت.
disabled	boolean	false	Disable the chip and keep it in its current state.
className	string	-	Additional Tailwind classes merged with the chip styles (last one wins).