Resumen
SegmentedControl es un preajuste compuesto por Radio y RadioGroup, con opciones unidas. Úsalo para una elección breve y mutuamente excluyente. Para navegar entre paneles de contenido, usa Tabs.
”Uso”
Proporciona un nombre de grupo accesible conaria-label o aria-labelledby. Cada opción necesita un value de cadena único. La selección pertenece al grupo; las opciones no tienen un estado de selección independiente.
defaultValue inicializa la selección. El grupo se encarga de los cambios posteriores. Agrega onValueChange si necesitas observarlos sin controlar el valor.
Estado controlado
value en el estado de la aplicación y actualízalo en onValueChange. No combines value y defaultValue ni cambies los modos de control después del montaje.
Opciones de icono
aria-label. startIcon es decorativo y está oculto para la tecnología de asistencia. Las opciones con texto visible usan label y también pueden proporcionar startIcon. Establece disabled en una opción para evitar su selección, o en el grupo para deshabilitar todas las opciones.
Teclado, formularios y dirección
Tab entra en el grupo; las teclas de flecha se mueven entre las opciones habilitadas y actualizan la selección. Esto sigue el comportamiento de los botones de opción. Los grupos de selección desplegables mueven el foco con las teclas de flecha y seleccionan al activarse.itemWidth="equal" es el valor predeterminado; usa content cuando las etiquetas deban determinar los anchos. Establece name para incluir el valor seleccionado en el envío nativo de formularios. El preajuste conserva las propiedades required y readOnly de RadioGroup, el estado deshabilitado y la integración con formularios nativos. onValueChange recibe el valor seleccionado y los detalles del evento de Base UI, incluidos reason y cancel().
Para contenido de derecha a izquierda, combina DirectionProvider con un atributo dir correspondiente. El proveedor controla la interacción direccional; dir controla el diseño del documento.
Composición y propiedades nativas
Las propiedades nativas,className, style, render y ref se aplican al div del grupo. Usa render para componer ese grupo con otro elemento; conserva su nombre accesible y la semántica de grupo de botones de opción. Las opciones representan elementos span con role="radio" y entradas de botones de opción nativas ocultas. El preajuste no asigna roles de pestaña ni de panel de pestañas. Para contenido de botones de opción personalizado, propiedades nativas por opción o un destino de representación de botones de opción diferente, compón Radio.Root y RadioGroup directamente.
”Props”
string
requerido
Accessible group name. Supply this or
aria-labelledby.string
requerido
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
predeterminado:"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
predeterminado:"false"
Stretch the control to the width of its container.
Ref<HTMLInputElement>
A ref to access the hidden input element.
"content" | "equal"
predeterminado:"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>[]
requerido
Options with a unique string
value, a label or startIcon, and optional disabled. Icon-only options require an aria-label.boolean
predeterminado:"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
predeterminado:"false"
Whether the user must choose a value before submitting a form.
"md" | "sm"
predeterminado:"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"
predeterminado:"round"
Shape:
round is a pill, rectangle fills its container with form-field corners.