Panoramica
SegmentedControl è un preset composto da Radio e RadioGroup, con opzioni unite. Usalo per una scelta breve e mutuamente esclusiva. Per la navigazione tra pannelli di contenuto, usa Tabs.
Utilizzo
Fornisci un nome di gruppo accessibile conaria-label o aria-labelledby. Ogni opzione necessita di una stringa value univoca. La selezione appartiene al gruppo; le opzioni non hanno uno stato selezionato indipendente.
defaultValue inizializza la selezione. Il gruppo gestisce le modifiche successive. Aggiungi onValueChange se devi osservarle senza controllare il valore.
Stato controllato
value nello stato dell’applicazione e aggiornalo in onValueChange. Non combinare value e defaultValue e non cambiare modalità di gestione dopo il montaggio.
Opzioni delle icone
aria-label. startIcon è decorativo ed è nascosto alla tecnologia assistiva. Le opzioni con testo visibile usano label e possono anche fornire startIcon. Imposta disabled su un’opzione per impedirne la selezione oppure sul gruppo per disabilitare tutte le opzioni.
Tastiera, moduli e direzione
Tab entra nel gruppo; i tasti freccia si spostano tra le opzioni abilitate e aggiornano la selezione. Questo segue il comportamento dei pulsanti radio. I gruppi di selezione a discesa spostano lo stato attivo con i tasti freccia e selezionano all’attivazione.itemWidth="equal" è il valore predefinito; usa content quando le etichette devono determinare le larghezze. Imposta name per includere il valore selezionato nell’invio del modulo nativo. La preimpostazione mantiene required, readOnly, lo stato disabled e l’integrazione con i moduli nativi di RadioGroup. onValueChange riceve il valore selezionato e i dettagli dell’evento Base UI, inclusi reason e cancel().
Per i contenuti da destra a sinistra, abbina DirectionProvider a un attributo dir corrispondente. Il provider controlla l’interazione direzionale; dir controlla il layout del documento.
Composizione e prop native
Le prop native,className, style, render e ref hanno come destinazione il div del gruppo. Usa render per comporre quel gruppo con un altro elemento; preservane il nome accessibile e la semantica del gruppo radio. Le opzioni eseguono il rendering di elementi span con role="radio" e input radio nativi nascosti. La preimpostazione non assegna ruoli di scheda o pannello di scheda. Per contenuti radio personalizzati, prop native per opzione o una destinazione di rendering radio diversa, componi direttamente Radio.Root e RadioGroup.
Props
string
obbligatorio
Accessible group name. Supply this or
aria-labelledby.string
obbligatorio
ID of an element that labels the group. Supply this or
aria-label.string | ((state: RadioGroupState) => string | undefined)
CSS class applied to the element, or a function that
returns a class based on the component’s state.
string
The uncontrolled value of the radio button that should be initially selected.To render a controlled radio group, use the
value prop instead.boolean
predefinito:"false"
Whether the component should ignore user interaction.
string
Identifies the form that owns the radio inputs.
Useful when the radio group is rendered outside the form.
boolean
predefinito:"false"
Stretch the control to the width of its container.
Ref<HTMLInputElement>
A ref to access the hidden input element.
"content" | "equal"
predefinito:"equal"
Use equal-width options or size each option to its content.
string
Identifies the field when a form is submitted.
((value: TValue, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)
Callback fired when the value changes.
readonly SegmentedControlOption<TValue>[]
obbligatorio
Options with a unique string
value, a label or startIcon, and optional disabled. Icon-only options require an aria-label.boolean
predefinito:"false"
Whether the user should be unable to select a different radio button in the group.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, RadioGroupState>
Allows you to replace the component’s HTML element
with a different tag, or compose it with another component.Accepts a
ReactElement or a function that returns the element to render.boolean
predefinito:"false"
Whether the user must choose a value before submitting a form.
"md" | "sm"
predefinito:"md"
Control height:
sm (24px) or md (32px).CSSProperties | ((state: RadioGroupState) => CSSProperties | undefined)
Style applied to the element, or a function that
returns a style object based on the component’s state.
string
The controlled value of the radio item that should be currently selected.To render an uncontrolled radio group, use the
defaultValue prop instead."rectangle" | "round"
predefinito:"round"
Shape:
round is a pill, rectangle fills its container with form-field corners.