# React Native Chip Group

> React Native choice chips for iOS, Android and the web: a row of pills that scrolls sideways, reveals the next chip when you tap one at the edge, with icons, scroll arrows and disabled chips. Zero native code.

# 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`](./segmented-control).

```tsx
import { ChipGroup } from 'patine-ui';
```

```tsx live
import { useState } from 'react';
import { ChipGroup } from 'patine-ui';

const cuisines = [
  'All', 'Italian', 'Japanese', 'Mexican', 'Indian', 'Thai', 'Chinese', 'Korean', 'Vietnamese', 'Greek',
  'Lebanese', 'Turkish', 'French', 'Spanish', 'Ethiopian', 'Peruvian', 'Brazilian', 'American', 'Vegan', 'Seafood',
].map((c) => ({ label: c, value: c }));

export default function Example() {
  const [cuisine, setCuisine] = useState('All');
  return <ChipGroup items={cuisines} value={cuisine} onValueChange={setCuisine} accessibilityLabel="Cuisine" />;
}
```

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

```tsx live
import { useState } from 'react';
import { ChipGroup, List, ListItem, VStack } from 'patine-ui';

const MENU = [
  { name: 'Burrata, peach and basil', section: 'Starters', price: 14 },
  { name: 'Charred octopus', section: 'Starters', price: 17 },
  { name: 'Cacio e pepe', section: 'Pasta', price: 19 },
  { name: 'Wild mushroom pappardelle', section: 'Pasta', price: 22 },
  { name: 'Lamb ragù', section: 'Pasta', price: 24 },
  { name: 'Grilled sea bass', section: 'Mains', price: 31 },
  { name: 'Tiramisu', section: 'Desserts', price: 10 },
  { name: 'Lemon sorbet', section: 'Desserts', price: 8 },
];
const SECTIONS = ['All', 'Starters', 'Pasta', 'Mains', 'Desserts'];

export default function Example() {
  const [section, setSection] = useState('All');
  const dishes = MENU.filter((d) => section === 'All' || d.section === section);
  const items = SECTIONS.map((s) => ({ value: s, label: `${s} ${s === 'All' ? MENU.length : MENU.filter((d) => d.section === s).length}` }));
  return (
    <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.

```tsx live
import { useState } from 'react';
import { ChipGroup } from 'patine-ui';

const countries = [
  ['🇺🇸', 'United States'], ['🇨🇦', 'Canada'], ['🇲🇽', 'Mexico'], ['🇧🇷', 'Brazil'], ['🇦🇷', 'Argentina'],
  ['🇬🇧', 'United Kingdom'], ['🇮🇪', 'Ireland'], ['🇫🇷', 'France'], ['🇩🇪', 'Germany'], ['🇪🇸', 'Spain'],
  ['🇵🇹', 'Portugal'], ['🇮🇹', 'Italy'], ['🇳🇱', 'Netherlands'], ['🇸🇪', 'Sweden'], ['🇳🇴', 'Norway'],
  ['🇬🇷', 'Greece'], ['🇹🇷', 'Turkey'], ['🇮🇱', 'Israel'], ['🇪🇬', 'Egypt'], ['🇿🇦', 'South Africa'],
  ['🇮🇳', 'India'], ['🇹🇭', 'Thailand'], ['🇻🇳', 'Vietnam'], ['🇯🇵', 'Japan'], ['🇰🇷', 'South Korea'],
  ['🇦🇺', 'Australia'], ['🇳🇿', 'New Zealand'],
].map(([flag, name]) => ({ label: name, value: name, icon: flag }));

export default function Example() {
  const [country, setCountry] = useState('Japan');
  return (
    <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.

```tsx live
import { useState } from 'react';
import { ChipGroup } from 'patine-ui';

const topics = [
  'For you', 'Following', 'Design', 'Engineering', 'React Native', 'TypeScript', 'Product', 'Startups', 'AI',
  'Open source', 'Accessibility', 'Performance', 'Testing', 'Animation', 'Career', 'Remote work', 'Writing',
].map((t) => ({ label: t, value: t }));

export default function Example() {
  const [topic, setTopic] = useState('For you');
  return (
    <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.

```tsx live
import { useState } from 'react';
import { ChipGroup, useTheme } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

const genres = [
  'Pop', 'Rock', 'Hip-hop', 'Jazz', 'Classical', 'Electronic', 'R&B', 'Country', 'Reggae', 'Metal', 'Folk', 'Blues', 'Latin', 'K-pop',
].map((g) => ({ label: g, value: g }));

export default function Example() {
  const theme = useTheme();
  const [genre, setGenre] = useState('Jazz');
  return (
    <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:

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { ChipGroup } from 'patine-ui';

const colors = [
  ['Black', '#1f1f1f'], ['White', '#f4f4f4'], ['Gray', '#9e9e9e'], ['Navy', '#1e3a8a'], ['Blue', '#3b82f6'],
  ['Green', '#16a34a'], ['Olive', '#708238'], ['Yellow', '#facc15'], ['Orange', '#f97316'], ['Red', '#dc2626'],
  ['Pink', '#ec4899'], ['Purple', '#9333ea'], ['Brown', '#8b5a2b'], ['Beige', '#d6c6a5'],
].map(([name, hex]) => ({
  label: name,
  value: name,
  icon: <View style={{ width: 14, height: 14, borderRadius: 7, backgroundColor: hex, borderWidth: 1, borderColor: 'rgba(0,0,0,0.15)' }} />,
}));

export default function Example() {
  const [color, setColor] = useState('Navy');
  return <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.

```tsx live
import { useState } from 'react';
import { ChipGroup } from 'patine-ui';

const soldOut = ['XS', 'XXL'];
const sizes = ['XS', 'S', 'M', 'L', 'XL', 'XXL', '3XL'].map((s) => ({ label: s, value: s, disabled: soldOut.includes(s) }));

export default function Example() {
  const [size, setSize] = useState('M');
  return <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:

```tsx live
import { useState } from 'react';
import { Text, View } from 'react-native';
import { ChipGroup } from 'patine-ui';

const dates = Array.from({ length: 21 }, (_, i) => {
  const date = new Date();
  date.setDate(date.getDate() + i);
  return date;
});
const days = dates.map((date, i) => ({ label: date.toDateString(), value: i }));

export default function Example() {
  const [day, setDay] = useState(0);
  return (
    <ChipGroup
      items={days}
      value={day}
      onValueChange={setDay}
      showArrows
      styles={{ item: { height: 60, minWidth: 48, borderRadius: 16 } }}
      renderItem={({ item, selected, theme }) => {
        const date = dates[item.value];
        const color = selected ? theme.colors.primary : theme.colors.text;
        return (
          <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 `radio`s 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](../guides/designs), 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`](./segmented-control): the same choice on one track
- [Menu with category chips example](/examples/category-chips): chips filtering a menu
- [Date range presets](./date-range-picker): the presets row is a `ChipGroup`
