chip

Allows people to make selections, filter content, or trigger actions

import { CdrChip, CdrChipGroup } from '@rei/cedar'

Live demo

Purpose

Chips allow users to make selections, filter content or trigger actions. While buttons are expected to appear consistently and with familiar calls to action, chips should appear dynamically.

TypePurpose
DefaultDirectly specifies, dynamically categorizes or immediately performs a discrete action.
StatefulUpdates settings immediately or triggers an immediate action while staying on the same page.
FilterAdds a visual representation of user-selected filters.
SelectionAllows users to make a single select choice or a multiple select choice.

Usage

When to use

  • Dynamically categorizing content based on descriptive words
  • Representing a checkbox group with more emphasis
  • Representing a radio button group with more emphasis
  • Clearly delineating and displaying options in a compact area
  • Offering dynamic and contextual actions related to primary content
  • Allowing the user to trigger an immediate action while staying on the same page
  • Allowing users to update or configure settings immediately

When not to use

  • Navigation is the goal. Instead, use a button or link
  • Displaying non-interactive elements
  • Displaying more than two rows of chips. Instead use horizontal scrolling or select
  • Representing page tags

Choosing the right component

CriteriaButtonLinkChip
Toggling a display to full screen——
Opening a modal window——
Triggering a popup menu——
Navigating users to a new page or view——
Changing the URL——
Causing a browser re-draw or refresh——
Representing a filtered list of content that appears on the same page——
Offering a choice or representing a filter——
Immediately changing a setting on the page——

Best practices

When arranging horizontally

  • Left align chip group
  • Separate each by cdr-space-half-x

A group of two chips arranged horizontally, separated by a space

When arranging vertically

  • Make sure chips overflow based on the width of the chip group area
  • Separate each by cdr-space-half-x

A group of three chips with one stacked vertically, separated by a space

Content

When using in a group

  • Use a logical order, whether it’s alphabetical, numerical, or time-based
  • Clearly communicate the effect of selecting the option
  • Provide a link or include a subtitle for more information. Don’t rely on tooltips to explain a radio button
  • For a more prominent alternative to radio buttons, use single select chip groups
  • For a more prominent alternative to checkboxes, use multiple select chip groups

Writing guidance

Do
Chip with text in sentence case

Do use sentence case with only proper nouns capitalized.

Don't
Chip with text in title case

Don't use title caps.

Do
Chip with line representing a brief amount of text

Do make text brief.

Don't
Chip with line representing too much text

Don't put too much text in the chip.

Do
Chip with text ending in no punctuation

Do write sentence fragments with no ending punctuation.

Don't
Chip with text ending in a period.

Don't add terminal punctuation.

Do
Chip with text using the positive phrasing: Set as my R.E.I.

Do use positive phrasing.

Don't
Chip with text using the negative phrasing: Do not set as my R.E.I.

Don't use negative phrasing for labels.

Behavior

CriteriaStatefulFilterSingle selectionMultiple selection
Can show confirmation feedback———
Automatically deselects all other chips in the group———
Includes more than one option per chip group———
Selecting one chip shouldn't change the selection status of another chip in the list———
Can optionally include an X remove icon———

Display

Do
A row of three chips with the next two overflowing into a new row.

Do allow a group of chips to overflow to a new row.

Don't
A row of two chips with a line break causing the next three chips to flow into a new row.

Don't create excessive line breaks in a group of chips.

Do
Two chips with different content sizes inside with the right amount of padding to acommodate their size.

Do allow chip containers to hug their contents.

Don't
Two chips containing different content sizes with extra padding making them the same width.

Don't add extra padding to make all chips the same width.

Do
Three chips labeled in order with sequential numbers.

Do display selection chips sequentially.

Don't
Three chips labeled out of order with random numbers.

Don't display selection chips in random order.

Do
Three chips in a group offering a selection.

Do display chips that offer a selection as a group.

Don't
A single chip incorrectly offering a selection.

Don't display a single chip to offer a selection.

Accessibility

What Cedar provides

  • CdrChip uses a button tag
  • CdrChipGroup implements keyboard navigation for a group of CdrChips

Development responsibilities

When using this component, here's what you are responsible for:

  • For a group of chips related to a single selection, use role=\"radio\", aria-checked, and tabindex on each chip and wrap the group in a CdrChipGroup component. The selected chip should have aria-checked="true" and tabindex="0" set, while the rest of the chips should have aria-checked="false" and tabindex="-1"
  • For a chip controlling a selection made elsewhere on the page, set aria-controls on the chip to point to the ID of the input being modified
  • For a chip that toggles a selection on and off, use role="switch" and aria-checked to designate its state
  • For other uses of CdrChip please reach out in Slack at #cedar-user-support"

Implementation

Icon slots

  • Place other icons in the icon-left slot
  • Use only one icon per chip
Do
Two chips grouped together with icons on the right.

Do use either icons in the right or the left slot per chip and chip group.

Don't
wo chips grouped together, one with mismatched icons on both the left and right.

Don't put icons in the right and left slots in a single chip or chip group.

Do
Chip with an x remove icon in the right slot.

Do use the X remove icon in the right slot.

Don't
Chip with an x remove icon incorrectly in the left slot.

Don't use the X remove icon in the left slot.

Stateful

  • For chips meant to toggle a single selection on and off, use the click event and dynamic properties to change the label or state of a chip
  • Use the aria-pressed attribute to designate the state of the toggle

Filter

  • Filter chips representing dynamically-removable user selections should include an X icon in the right icon slot and link to the ID of the input it controls using aria-controls
  • The aria-pressed property should be set to true to designate that this selection is active
  • Filter chips linked to a checkbox should appear selected and be included in the same form group as the checkboxes

Selection

Single select

  • For single select chip groups, apply role='radio' to each chip, use aria-checked="true" and tabindex="0" to designate the selected chip, and apply aria-checked="false" and tabindex="-1" to the other chips
  • Group the chip elements directly inside a CdrChipGroup element to ensure keyboard navigation is properly managed
  • Pass in a label property or slot which describes CdrChipGroup. This label is visually hidden by default

Multiple select

  • For multiple select chip groups, apply role='checkbox' to each chip, use aria-checked="true" to designate the selected chip, and apply aria-checked="false" to the other chips"
  • Group the chip elements directly inside a CdrChipGroup element to ensure keyboard navigation is properly managed
  • Pass in a label property or slot which describes CdrChipGroup. This label is visually hidden by default

API

CdrChip

Slots

Name
icon-left

Icon to the left of the content

icon-right

Icon to the right of the content

default

Primary CdrChip content

CdrChipGroup

Props

NameTypeDefault
label
Required

Sets a label that describes the chip group and what it is selecting. By default this label is visually hidden and only made available to screen readers.

string
hideLabel

Visually hides the chip group label but makes it accessible to screen readers.

booleantrue

Slots

Name
label

Override CdrChip label content with a custom element

default

CdrChipGroup content (CdrChip components)