Segmented Control

OverviewAnalyticsReportsSettings

Contract

Overview

Machine-readable contract from Component Spec.

component: segmented-controlexport: SegmentedControlversion: 1recipe: segmented-controltokens.visual: segmentedControlattributes: data-refineui=segmented-control

Anatomy

Part	data-refineui
root	segmented-control
indicator	segmented-control-indicator
item	segmented-control-item

States

Scope	Category	Values
component	pseudo	focus-visible
component	environment	forced-colors, dir, prefers-contrast

Accessibility

Slot	Element	Role	Required attributes
segmented-control	div	radiogroup	—
segmented-control-item	button	radio	aria-checked: required=true, type: boolean

Keyboard

Key	Action	Native
Enter	activate	true
Space	activate	true

Focus

Section	Property	Value
visual	required	true
visual	selector	:focus-visible
behavior	roving	true

Layout

Property	Value
direction	logical
rtl	true

Tokens

Variant

Select a recipe variant — preview and Recipe → Tokens update together.

OverviewAnalyticsReports

Recipe → Tokens

Slot bindings for variant="selected" — declared in segmented-control.recipe.ts.

Slot	Variant	Property	Trace	Semantic	Light → foundation	Dark → foundation	Recipe class
root	—	background	segmentedControl.barBackground	backgroundBrandSubtle	primaryLightGray	neutral800	bg-refineui-alias-background-brand-subtle
root	—	border	segmentedControl.barBorder	borderDefault	neutral300	neutral650	border-refineui-alias-border-default
indicator	—	background	segmentedControl.selectedBackground	backgroundBrand	primaryBlack	primaryGray	bg-refineui-alias-background-brand
item	—	foreground	segmentedControl.itemForeground	foregroundSecondary	neutral600	neutral350	text-refineui-alias-foreground-secondary
item	selected	foreground	segmentedControl.selectedForeground	foregroundOnBrand	neutralWhite	neutralBlack	text-refineui-alias-foreground-on-brand

Component token trace

All paths in token-trace-v2.json prefixed with segmentedControl.

Trace	Semantic	Light foundation	Dark foundation	Light	Dark
segmentedControl.barBackground	backgroundBrandSubtle	primaryLightGray	neutral800	#E6E6E6	#2A2A2A
segmentedControl.barBorder	borderDefault	neutral300	neutral650	#DBDBDB	#5B5B5B
segmentedControl.hoverForeground	foregroundPrimary	primaryBlack	neutralWhite	#212121	#FFFFFF
segmentedControl.itemDisabledForeground	foregroundDisabled	neutral400	neutral600	#CECECE	#6C6C6C
segmentedControl.itemForeground	foregroundSecondary	neutral600	neutral350	#6C6C6C	#D8D8D8
segmentedControl.selectedBackground	backgroundBrand	primaryBlack	primaryGray	#212121	#D4D4D4
segmentedControl.selectedDisabledBackground	backgroundSurfaceDisabled	neutral150	neutral850	#F0F0F0	#222222
segmentedControl.selectedForeground	foregroundOnBrand	neutralWhite	neutralBlack	#FFFFFF	#000000
segmentedControl.selectedHoverBackground	backgroundBrandHover	primaryDarkGray	primaryLightGray	#4d4d4d	#E6E6E6

Installation

npmyarnpnpmbun

npm install @refineui/react @refineui/tokens

Usage

import { SegmentedControl, SegmentedControlItem } from "@refineui/react";

<SegmentedControl value={view} onValueChange={setView}>
  <SegmentedControlItem value="grid">Grid</SegmentedControlItem>
  <SegmentedControlItem value="list">List</SegmentedControlItem>
</SegmentedControl>

The selected thumb is a sliding brand indicator. Until geometry is ready (data-ready), the selected item keeps a brand fill so the first paint is not blank. After the first layout, transform leads width slightly so the slide feels less mechanical.

API Reference

SegmentedControl

Prop	Default	Type	Description
value	—	string	Controlled selected value.
defaultValue	—	string	Uncontrolled initial value.
onValueChange	—	(value: string) => void	Event handler when selection changes.

SegmentedControlItem

Prop	Default	Type	Description
value	—	string	Unique value for this option (required).
disabled	false	boolean	Disables this option.