Segmented Control React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Usage

Import SegmentedControl from @/components/ui/segmented-control.

import { useState } from "react"
import { SegmentedControl, type SegmentedControlOption } from "@/components/ui/segmented-control"

const periods: SegmentedControlOption[] = [
  { value: "day", label: "Day" },
  { value: "week", label: "Week" },
  { value: "month", label: "Month" },
  { value: "year", label: "Year" },
]

export function SalesPeriod() {
  const [period, setPeriod] = useState("week")
  return (
    <SegmentedControl
      aria-label="Period"
      options={periods}
      value={period}
      onValueChange={setPeriod}
      fullWidth
    />
  )
}

Props

• options*
  SegmentedControlOption[]

  The options: { value, label?, icon?, disabled?, badge?, tooltip? }. 2 to 5 read best; more still fit with truncated labels (use tabs then). A number badge renders a small count that hides at 0.

• value
  string

  The selected option, when you control it. A value that is not in options shows no thumb.

• defaultValuedefault ""
  string

  The option selected on the first render when uncontrolled. Empty, or a value that is not in options, starts on the first enabled option.

• onValueChange
  (value: string) => void

  Called with the new value on click, arrow keys, Home / End and while dragging the thumb.

• sizedefault "md"
  "sm" | "md" | "lg"

  Track height 32 / 40 / 48px with matching type and icon size; options fill it inside a 2px padding. On touch screens md grows to 44px and sm keeps its look with a 44px hit area.

• radiusdefault "md"
  "none" | "sm" | "md" | "lg" | "full"

  Corner shape of the track, scaled with the size like the button's. The thumb is 2px rounder-in so the gap stays even.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The thumb's color. neutral is a raised white surface (a lifted gray in dark mode) like iOS; the other tones fill the thumb and turn its label to the tone's foreground.

• colordefault ""
  string

  Any CSS color for the thumb. Replaces the tone; the label on it turns black or white by lightness. Leave empty to use the tone.

• dividersdefault true
  boolean

  Hairlines between unselected neighbours. The ones touching the thumb fade out, like iOS.

• iconOnlydefault false
  boolean

  Shows only the icons. Each label becomes the option's aria-label and its tooltip, so the control stays readable.

• fullWidthdefault false
  boolean

  Stretches the track to its container and shares the width between options. The usual layout on a phone.

• draggabledefault true
  boolean

  Press the thumb and slide sideways to change the value, with touch or a mouse. Vertical swipes still scroll the page.

• loopdefault true
  boolean

  Arrow keys wrap from the last option to the first and back. Off, they stop at the ends.

• disableddefault false
  boolean

  Dims the whole control and blocks it. Disable single options with option.disabled.

• aria-labeldefault ""
  string

  The group's name for screen readers. Required when no visible label names the control.

• namedefault ""
  string

  Form field name. Inside a <form> the selected value is submitted like a radio group.

• dirdefault "ltr"
  "ltr" | "rtl"

  Reading direction; rtl mirrors the layout, the arrow keys and the drag. Left out, it follows a Radix DirectionProvider, else ltr.

• classNames
  Partial<Record<"item" | "thumb" | "icon" | "label" | "badge" | "divider", string>>

  Extra classes for the inner parts.

• className
  string

  Extra classes for the track, merged last.

Parts

FAQ

Used in

More React input components