{ "name": "SegmentedControl", "source": "src/components/SegmentedControl.tsx", "propsType": "SegmentedControlProps", "description": "SegmentedControl — pick one of a few options, and see all of them.\n\nNOT TABS, ALTHOUGH IT LOOKS LIKE THE PILL TYPE, and the difference is the\ncontract. Tabs switch between panels: `tablist`, `tab`, `tabpanel`, and each\ntab controls a region. This sets a VALUE — a view mode, a time range, a\nunit — and controls no panel. It is a `radiogroup`, so it has one tab stop,\narrow keys move and select, and it submits with a form like any radio.\n\nBuilt from real radio inputs, visually hidden, not from buttons with\n`aria-pressed`. A row of toggle buttons is a tab stop per option and no\nmutual exclusion that assistive tech can announce; radios give \"2 of 3,\nselected\" for free.\n\nThe look is Tabs' pill track, token for token, so the two cannot drift\napart visually — which is exactly why the intent file spends its words on\nwhen to use which.", "import": "import { SegmentedControl } from 'ionbase-ui';", "status": "stable", "summary": "Pick one of two to five options, all visible at once. A radio group drawn as a segmented track — it sets a value and controls no panel.", "useWhen": [ "switching how the same content is shown — List / Board / Calendar", "a short, fixed set of mutually exclusive settings — Day / Week / Month, °C / °F", "a filter with a few exclusive choices where seeing every option matters" ], "useInstead": [ { "when": "each option shows a different panel of content", "use": "Tabs", "why": "Tabs wires each tab to its panel with tablist/tabpanel semantics. A SegmentedControl controls no region, so a screen-reader user is never told which content changed" }, { "when": "there are more than five options, or the labels are long", "use": "Select", "why": "segments do not wrap; a track that overflows hides the options it exists to show" }, { "when": "the choice sits in a form with a visible question and descriptions per option", "use": "RadioGroup", "why": "same semantics, but room for a label and helper text on each option" }, { "when": "the setting is a single on/off", "use": "Toggle" }, { "when": "the options trigger actions rather than set a value — Bold, Italic", "use": "Button", "why": "an action is not a selection; a radio group announces a state that does not exist" } ], "composition": { "order": [ "SegmentedControl", "SegmentedControlItem" ], "example": "ListBoard" }, "variants": { "size": { "sm": { "use": "toolbars and dense panel headers" }, "md": { "use": "the default" }, "lg": { "use": "a primary view switch at the top of a page" } } }, "slots": { "children": { "accepts": "SegmentedControlItem", "note": "two to five. One item is not a choice; six is a Select" } }, "a11y": { "role": "radiogroup / radio", "requires": [ "`label` — the group's accessible name. Hidden by default; `showLabel` renders it above the track" ], "guarantees": [ "one tab stop for the whole control; arrow keys move and select, skipping disabled segments", "built from real radio inputs, so it announces \"2 of 3, selected\" and submits with a form under `name`", "a disabled selected segment keeps its selected surface — a disabled control still has a value" ], "notes": [ "it looks exactly like Tabs' pill type on purpose, and behaves differently on purpose. Choose by what changes, not by how it looks" ] }, "antiPatterns": [ { "dont": "a SegmentedControl that swaps the panel below it", "do": "", "why": "the panel relationship is exactly what tabpanel semantics announce; without it the content changes silently" }, { "dont": "no defaultValue or value", "why": "a segmented track with nothing selected reads as broken, not as a choice still to make" }, { "dont": "icon-only segments with no aria-label", "do": "} aria-label=\"Grid view\" />", "why": "each segment is a radio, and an unnamed radio is announced as just \"radio button\"" } ], "stylesheet": "src/styles/segmented-control.css", "tokens": [ "--border-width-thick", "--font-family-sans", "--font-weight-medium", "--icon-size-md", "--icon-size-sm", "--ion-duration-base", "--ion-ease-out", "--ion-segmented-font-size", "--ion-segmented-icon-size", "--ion-segmented-item-gap", "--ion-segmented-item-height", "--ion-segmented-item-padding-x", "--ion-segmented-line-height", "--radius-lg", "--radius-md", "--ring-focus", "--spacing-12", "--spacing-16", "--spacing-2", "--spacing-20", "--spacing-24", "--spacing-32", "--spacing-4", "--spacing-40", "--spacing-6", "--spacing-8", "--surface-default", "--surface-hover", "--surface-muted", "--surface-page", "--text-default", "--text-disabled", "--text-tertiary", "--type-body", "--type-body-lg", "--type-body-lg-line-height", "--type-body-line-height", "--type-body-sm", "--type-body-sm-line-height" ], "props": { "label": { "type": "string", "required": true, "origin": "own", "description": "The accessible name of the group. Required: \"List, Board, Calendar\" means\nnothing until something says they are views." }, "showLabel": { "type": "boolean | undefined", "required": false, "origin": "own", "description": "Show `label` above the control, as a form field does. Hidden by default.", "default": false }, "value": { "type": "string | undefined", "required": false, "origin": "own", "description": "Controlled selected value. Pass `onChange` with it." }, "defaultValue": { "type": "string | undefined", "required": false, "origin": "own", "description": "Uncontrolled starting value. One option should always be selected — a\nsegmented control with nothing chosen reads as broken, not as \"no choice\"." }, "onChange": { "type": "((value: string) => void) | undefined", "required": false, "origin": "own" }, "size": { "type": "SegmentedControlSize | undefined", "required": false, "origin": "own", "values": [ "sm", "md", "lg" ], "default": "md" }, "isFullWidth": { "type": "boolean | undefined", "required": false, "origin": "own", "description": "Stretch to the container, with equal-width segments.", "default": false }, "isDisabled": { "type": "boolean | undefined", "required": false, "origin": "own", "default": false }, "name": { "type": "string | undefined", "required": false, "origin": "own", "description": "Submitted with a form under this name." }, "children": { "type": "React.ReactNode", "required": false, "origin": "own", "description": "`SegmentedControlItem` elements. Two to five of them." }, "className": { "type": "string | undefined", "required": false, "origin": "own" } }, "propCounts": { "own": 11, "aria": 0, "dom": 0, "other": 0 } }