Skip to main content

SegmentedControl

SegmentedControl picks one of a few options on a track, with the selected one on a sliding thumb. Items share the track's width while they fit, and the track scrolls sideways when they don't. For separate pills, such as filters, use ChipGroup.

import { SegmentedControl } from 'patine-ui';
Loading…
<SegmentedControl items={views} value={view} onValueChange={setView} accessibilityLabel="Calendar view" />

Try the props​

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

Example: a fitness summary​

A fitness app's activity card: Week, Month and Year switch the bars and the total, and the control stays the same width whichever is picked.

Loading…
<Box border radius="lg" padding="md" gap="md" style={{ width: '100%', maxWidth: 400 }}>
  <SegmentedControl
    items={[{ label: 'Week', value: 'week' }, { label: 'Month', value: 'month' }, { label: 'Year', value: 'year' }]}
    value={range}
    onValueChange={setRange}
    accessibilityLabel="Time range"
  />
  <VStack>
    <Text size="3xl" weight="semibold">{values.reduce((a, b) => a + b, 0)} {unit}</Text>
    <Text color="textSecondary">Running, this {range}</Text>
  </VStack>
  <HStack gap="xs" align="flex-end" style={{ height: 120 }} accessibilityLabel={labels.map((l, i) => `${l} ${values[i]} ${unit}`).join(', ')}>
    {values.map((v, i) => (
      <VStack key={i} gap="xs" align="center" style={{ flex: 1 }}>
        <View style={{ width: '70%', height: max ? (v / max) * 96 + 2 : 2, borderRadius: 4, backgroundColor: v ? '#0EA5E9' : '#E5E7EB' }} />
        <Text size="xs" color="textSecondary">{labels[i]}</Text>
      </VStack>
    ))}
  </HStack>
</Box>

Many options​

A few items share the track's width. With more than fit, the track scrolls, and the thumb follows the selection along it. In the Material design there's no thumb: the segments are outlined, as in Material's segmented buttons, and the chosen one is filled and shows a ✓ in place of its icon.

Loading…
<View style={{ gap: 16 }}>
  <SegmentedControl items={sorts} value={sort} onValueChange={setSort} accessibilityLabel="Sort by" />
  <SegmentedControl items={ranges} value={range} onValueChange={setRange} accessibilityLabel="Chart range" />
</View>

Icons​

Give an item 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 also be a function of { selected, disabled, color }, to color it like its label.

Loading…
<SegmentedControl items={views} value={view} onValueChange={setView} iconPosition="top" accessibilityLabel="Show listings as" />

Any value type​

Values can be anything: numbers, ids, objects. SegmentedControl<T> infers T from items, so onValueChange gets the typed value.

Loading…
<View style={{ gap: 12 }}>
  <SegmentedControl items={tips} value={tip} onValueChange={setTip} accessibilityLabel="Tip" />
  <Text style={{ color: theme.colors.text, fontSize: 16 }}>Total: ${(bill * (1 + tip / 100)).toFixed(2)}</Text>
</View>

Object values are compared with Object.is. When they're recreated (say, refetched from a server), pass isEqual:

<SegmentedControl items={plans} value={plan} onValueChange={setPlan} isEqual={(a, b) => a.id === b.id} />

Behaviour​

  • Controlled: pass value and update it in onValueChange. Tapping the selected item calls onValueChange again.
  • The thumb slides to the selected item (in Material, the selected segment is filled instead).
  • Tapping an item whose neighbor is hidden scrolls that neighbor into view, plus a little of the one after it, so the user sees there's more.
  • showArrows adds ‹ › buttons, as in ChipGroup. The arrows need a frame around the list: style lays out that frame and styles.container styles the track itself.

Accessibility​

The control is a radiogroup named by accessibilityLabel; items are radios with checked and disabled states. Arrow keys move between items 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 (the track in segmented)
contentThe row inside it
item / selectedItemEach item / the selected one
itemLabel / selectedItemLabelItem label
thumbThe sliding thumb (segmented, not in Material)
arrow / arrowTextEach scroll arrow / its glyph (showArrows)