Skip to main content

ChipGroup

ChipGroup picks one option from a row of separate pills, such as a category, a filter or a size. The row scrolls sideways, and tapping the last visible chip scrolls the next one into view, so the user sees there's more. For a few options on one track, use SegmentedControl.

import { ChipGroup } from 'patine-ui';
Loading…
<ChipGroup items={cuisines} value={cuisine} onValueChange={setCuisine} accessibilityLabel="Cuisine" />

Try the props​

Props
iconPosition
arrowPosition
<ChipGroup
items={views}
value={view}
onValueChange={setView}
/>

Example: filter a menu​

A restaurant's ordering screen: the chips pick a section of the menu and show how many dishes it holds, and the list below follows them.

Loading…
<VStack gap="sm" style={{ width: '100%', maxWidth: 440 }}>
  <ChipGroup items={items} value={section} onValueChange={setSection} accessibilityLabel="Menu section" />
  <List>
    {dishes.map((dish) => (
      <ListItem key={dish.name} title={dish.name} description={dish.section} value={`€${dish.price}`} onPress={() => {}} />
    ))}
  </List>
</VStack>

Scroll arrows​

showArrows adds round ‹ › buttons that scroll the list about a page. They're off by default: swiping already scrolls on touch screens, so arrows help most with a mouse on the web, or a long row of chips.

By default (arrowPosition="outside") the arrows sit beside the list and show while its items overflow; the one that can't scroll further is dimmed, so the list keeps its width.

Loading…
<ChipGroup items={countries} value={country} onValueChange={setCountry} showArrows accessibilityLabel="Country" />

Over the edges​

arrowPosition="overlay" floats the arrows over the list's edges instead, each shown only while items are hidden past it, so the list keeps its full width.

Loading…
<ChipGroup
  items={topics}
  value={topic}
  onValueChange={setTopic}
  showArrows
  arrowPosition="overlay"
  accessibilityLabel="Topic"
/>

Custom arrows​

renderArrow(side, disabled) replaces the ‹ › glyph, and the arrow slot styles the button around it.

Loading…
<ChipGroup
  items={genres}
  value={genre}
  onValueChange={setGenre}
  showArrows
  renderArrow={(side, disabled) => (
    <Icon name={side === 'left' ? 'arrowLeft' : 'arrowRight'} size="sm" strokeWidth={2} color={disabled ? 'textDisabled' : 'primary'} />
  )}
  styles={{ arrow: { backgroundColor: theme.colors.primaryMuted, borderWidth: 0, boxShadow: 'none' } }}
  accessibilityLabel="Genre"
/>

Icons​

Give a chip an icon and choose its side with iconPosition: 'left' (the default), 'right', 'top' or 'bottom'. 'left' and 'right' follow the layout direction, so they swap in RTL. An icon can be any view, or a function of { selected, disabled, color } to color it like its label. Here each color filter has a swatch:

Loading…
<ChipGroup items={colors} value={color} onValueChange={setColor} accessibilityLabel="Color" />

Disabled items​

A disabled item is dimmed and can't be chosen, like sizes that are sold out.

Loading…
<ChipGroup items={sizes} value={size} onValueChange={setSize} accessibilityLabel="Size" />

Custom items​

renderItem draws each item's content, and the item slot resizes the pill around it. Here, a strip of the next three weeks:

Loading…
      <View style={{ alignItems: 'center', gap: 2 }}>
        <Text style={{ fontSize: 11, color: selected ? theme.colors.primary : theme.colors.textSecondary }}>
          {item.value === 0 ? 'Today' : date.toLocaleDateString(undefined, { weekday: 'short' })}
        </Text>
        <Text style={{ fontSize: 18, fontWeight: '700', color }}>{date.getDate()}</Text>
      </View>
    );
  }}
  accessibilityLabel="Day"
/>

Behaviour​

  • Controlled: pass value and update it in onValueChange. Tapping the selected chip calls onValueChange again.
  • Tapping a chip whose neighbor is hidden scrolls that neighbor into view, plus a little of the one after it.
  • With showArrows, the arrows need a frame around the list: style lays out that frame and styles.container styles the list itself.
  • In the Material design, chips are outlined and the chosen one is filled with a ✓.

Accessibility​

The group is a radiogroup named by accessibilityLabel; chips are radios with checked and disabled states. Scroll arrows are buttons labelled "Scroll left" and "Scroll right". Arrow keys move between chips on the web.

Props​

PropTypeDefaultDescription
itemsReadonlyArray<ChoiceItem<T>>required{ label, value, disabled?, icon? }. icon is a node, or a function of { selected, disabled, color }.
valueT | null—Selected value.
onValueChange(value: T, item) => void—Called on tap.
iconPosition'left' | 'right' | 'top' | 'bottom''left'Where each icon sits around its label.
showArrowsbooleanfalseRound ‹ › buttons that scroll about a page, shown while the items overflow.
arrowPosition'outside' | 'overlay''outside'Beside the list, the one that can't scroll further dimmed; or over its edges, each shown while items hide past it.
renderArrow(side: 'left' | 'right', disabled: boolean) => ReactNode—Custom arrow content.
isEqual(a: T, b: T) => booleanObject.isValue equality.
renderItem(info: { item, selected, disabled, theme }) => ReactNode—Custom item content.
accessibilityLabelstring—Names the list for screen readers.
styleStyleProp<ViewStyle>—Container style.
stylesSlotStyles<ChoiceSlot>—Slots below.
themeDeepPartial<Theme>—Theme override.
design'brand' | 'ios' | 'material' | 'web' | 'native'from PatineProviderThe look to follow, over the provider's: brand, iOS, Material or web, or 'native' for the platform's own.
testIDstring—Test ID; items get {testID}-item-{index}, arrows {testID}-arrow-left / {testID}-arrow-right.

Slots​

SlotElement
containerThe scroll view
contentThe row inside it
item / selectedItemEach item / the selected one
itemLabel / selectedItemLabelItem label
arrow / arrowTextEach scroll arrow / its glyph (showArrows)