Skip to content
React NativeBetaMobile only

SegmentedControl

A row of mutually exclusive (or, with `multiple`, combinable) options, iOS style.

Beta. React Native support is in beta. APIs may change or break between prereleases (npm tag native).

On this page
Web preview — real device may differ
tsx
import { useState } from "react";
import { Text, View } from "react-native";
import { useKitTheme } from "@/component-lib/shared/native";
import { SegmentedControl } from "@/component-lib/segmented-control";
import { Section } from "./layout"; // Section and Row: page layout for the demo
 
export function SegmentedControlDemo() {
  const { tokens } = useKitTheme();
  const [period, setPeriod] = useState("week");
  const [days, setDays] = useState<string[]>(["mon", "wed"]);
  const note = { color: tokens.muted, fontSize: tokens.fontSize - 2 };
  return (
    <>
      <Section title="SegmentedControl · thumb (iOS)">
        <SegmentedControl
          aria-label="Period"
          value={period}
          onValueChange={setPeriod}
          options={[
            { value: "day", label: "Day" },
            { value: "week", label: "Week" },
            { value: "month", label: "Month" },
            { value: "year", label: "Year" },
          ]}
        />
        <Text style={note}>Value: {period}</Text>
        <View style={{ gap: 10 }}>
          <SegmentedControl
            aria-label="View"
            size="sm"
            fullWidth={false}
            options={[
              { value: "list", label: "List" },
              { value: "grid", label: "Grid" },
              { value: "map", label: "Map", disabled: true },
            ]}
          />
        </View>
      </Section>
      <Section title="SegmentedControl · check (Material 3)">
        <SegmentedControl
          aria-label="Unit"
          indicator="check"
          defaultValue="kg"
          options={[
            { value: "kg", label: "kg" },
            { value: "lb", label: "lb" },
          ]}
        />
        <SegmentedControl
          aria-label="Delivery days"
          multiple
          value={days}
          onValueChange={setDays}
          options={[
            { value: "mon", label: "Mon" },
            { value: "tue", label: "Tue" },
            { value: "wed", label: "Wed" },
            { value: "thu", label: "Thu" },
          ]}
        />
        <Text style={note}>Days: {days.join(", ") || "none"}</Text>
        <SegmentedControl
          aria-label="Disabled"
          disabled
          options={[
            { value: "a", label: "Off" },
            { value: "b", label: "On" },
          ]}
        />
      </Section>
    </>
  );
}

Install

npx @grampro/kit@native add SegmentedControl

Usage

tsx
import { SegmentedControl } from "@/component-lib/segmented-control";
 
<SegmentedControl
  value={range}
  onValueChange={setRange}
  options={[
    { value: "day", label: "Day" },
    { value: "week", label: "Week" },
    { value: "month", label: "Month" },
  ]}
/>

Props

SingleSegmentedControlProps

PropTypeDescription
multiplefalse
valuestring
defaultValuestring
onValueChange(value: string) => void
options (required)SegmentedOption[]
size"sm" | "md"Default md.
fullWidthbooleanStretch to the container's width; segments share it equally. Default true.
indicator"thumb" | "check"thumb: a raised pill slides to the selection (iOS). check: outlined segments, the selected ones filled with a check (Material 3). Default thumb; multiple selection always uses check.
disabledboolean
styleStyleProp<ViewStyle>
stylesPartial<{ root: StyleProp<ViewStyle>; segment: StyleProp<ViewStyle>; label: StyleProp<T…

MultipleSegmentedControlProps

PropTypeDescription
multiple (required)true
valuestring[]
defaultValuestring[]
onValueChange(value: string[]) => void
options (required)SegmentedOption[]
size"sm" | "md"Default md.
fullWidthbooleanStretch to the container's width; segments share it equally. Default true.
indicator"thumb" | "check"thumb: a raised pill slides to the selection (iOS). check: outlined segments, the selected ones filled with a check (Material 3). Default thumb; multiple selection always uses check.
disabledboolean
styleStyleProp<ViewStyle>
stylesPartial<{ root: StyleProp<ViewStyle>; segment: StyleProp<ViewStyle>; label: StyleProp<T…

Notes

  • With multiple, value is an array of selected values.
  • Mobile only: there is no web version of this component.