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';
<ChipGroup items={cuisines} value={cuisine} onValueChange={setCuisine} accessibilityLabel="Cuisine" />
Try the props
iconPositionarrowPosition<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.
<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.
<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.
<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.
<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:
<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.
<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:
<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
valueand update it inonValueChange. Tapping the selected chip callsonValueChangeagain. - 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:stylelays out that frame andstyles.containerstyles 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
| Prop | Type | Default | Description |
|---|---|---|---|
items | ReadonlyArray<ChoiceItem<T>> | required | { label, value, disabled?, icon? }. icon is a node, or a function of { selected, disabled, color }. |
value | T | null | — | Selected value. |
onValueChange | (value: T, item) => void | — | Called on tap. |
iconPosition | 'left' | 'right' | 'top' | 'bottom' | 'left' | Where each icon sits around its label. |
showArrows | boolean | false | Round ‹ › 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) => boolean | Object.is | Value equality. |
renderItem | (info: { item, selected, disabled, theme }) => ReactNode | — | Custom item content. |
accessibilityLabel | string | — | Names the list for screen readers. |
style | StyleProp<ViewStyle> | — | Container style. |
styles | SlotStyles<ChoiceSlot> | — | Slots below. |
theme | DeepPartial<Theme> | — | Theme override. |
design | 'brand' | 'ios' | 'material' | 'web' | 'native' | from PatineProvider | The look to follow, over the provider's: brand, iOS, Material or web, or 'native' for the platform's own. |
testID | string | — | Test ID; items get {testID}-item-{index}, arrows {testID}-arrow-left / {testID}-arrow-right. |
Slots
| Slot | Element |
|---|---|
container | The scroll view |
content | The row inside it |
item / selectedItem | Each item / the selected one |
itemLabel / selectedItemLabel | Item label |
arrow / arrowText | Each scroll arrow / its glyph (showArrows) |
Related
SegmentedControl: the same choice on one track- Menu with category chips example: chips filtering a menu
- Date range presets: the presets row is a
ChipGroup