Segmented Control

Use a segmented control to choose one value from a short list of options.

<sa-segmented-control name="travel-mode" value="Flights" aria-label="Travel mode">
    <sa-segmented-control-item value="Flights">Flights</sa-segmented-control-item>
    <sa-segmented-control-item value="Stays">Stays</sa-segmented-control-item>
    <sa-segmented-control-item value="Cars">Cars</sa-segmented-control-item>
</sa-segmented-control>

Usage

Place <sa-segmented-control-item> elements inside <sa-segmented-control>. Each item requires a value; its content provides the label. For unbound controls, supply a unique field name and an optional initial value on the parent. With no matching value, no option is selected.

Icons

Place an <sa-icon> alongside each option’s text. The icon is decorative; the text supplies the accessible label.

<sa-segmented-control name="travel-mode-icons" value="Flights" aria-label="Travel mode">
    <sa-segmented-control-item value="Flights">
        <sa-icon name="plane" aria-hidden="true" />
        Flights
    </sa-segmented-control-item>
    <sa-segmented-control-item value="Stays">
        <sa-icon name="bed-double" aria-hidden="true" />
        Stays
    </sa-segmented-control-item>
    <sa-segmented-control-item value="Cars">
        <sa-icon name="car-front" aria-hidden="true" />
        Cars
    </sa-segmented-control-item>
</sa-segmented-control>

Model binding

Set asp-for on the parent. It supplies the radio group name and selected value, taking precedence over name and value. String, enum, and nullable properties use normal ASP.NET Core model binding. Submitted values are preserved when redisplaying a form with validation errors, including nested field prefixes.

<sa-segmented-control asp-for="Cabin">
    <sa-segmented-control-item value="Economy">Economy</sa-segmented-control-item>
    <sa-segmented-control-item value="Business">Business</sa-segmented-control-item>
    <sa-segmented-control-item value="First">First</sa-segmented-control-item>
</sa-segmented-control>

Binding automatically renders the standard field wrapper with its label, description, and validation message. Use label, description, and error to provide explicit field text. Set render-field="false" to render only the control, or compose it inside <sa-field> with <sa-field-label>, <sa-field-description>, and <sa-field-error>; nesting inside a field suppresses the automatic wrapper. For custom help and error elements, aria-describedby on the control is also applied to its radios. Model metadata supplies the accessible group name and required state; aria-label or aria-labelledby overrides the name, and required overrides the required state. Form submission sends the selected enabled radio's value. An unselected group sends no value.

<sa-segmented-control asp-for="Cabin">
    <sa-segmented-control-item value="Economy">Economy</sa-segmented-control-item>
    <sa-segmented-control-item value="Business">Business</sa-segmented-control-item>
    <sa-segmented-control-item value="First">First</sa-segmented-control-item>
</sa-segmented-control>

Change event

Attach the standard onchange handler to the outer component, or use addEventListener("change", handler) on its rendered element. The native event bubbles from the selected radio: event.target.value contains the new value and event.currentTarget is the outer control.

<sa-stack>
    <sa-segmented-control name="trip-view" value="List" aria-label="Trip view"
                          onchange="document.getElementById('trip-view-result').textContent = event.target.value">
        <sa-segmented-control-item value="List">List</sa-segmented-control-item>
        <sa-segmented-control-item value="Map">Map</sa-segmented-control-item>
    </sa-segmented-control>
    <p>Selected view: <output id="trip-view-result" aria-live="polite">List</output></p>
</sa-stack>

Selecting a different option fires one change event. Initialization, selecting the current option again, form reset, and assigning a radio's checked property do not fire a change event. Programmatic callers can explicitly dispatch a bubbling change event when they need to notify listeners. Selection styling and form behavior work without StellarAdmin JavaScript.

Disabled

Set disabled="true" on an item or the entire control. Disabled radios cannot be selected and are excluded from form submission.

<sa-stack>
    <sa-segmented-control name="available-travel" value="Flights" aria-label="Available travel">
        <sa-segmented-control-item value="Flights">Flights</sa-segmented-control-item>
        <sa-segmented-control-item value="Stays">Stays</sa-segmented-control-item>
        <sa-segmented-control-item value="Cars" disabled="true">Cars</sa-segmented-control-item>
    </sa-segmented-control>
    <sa-segmented-control name="locked-travel" value="Stays" disabled="true" aria-label="Locked travel">
        <sa-segmented-control-item value="Flights">Flights</sa-segmented-control-item>
        <sa-segmented-control-item value="Stays">Stays</sa-segmented-control-item>
        <sa-segmented-control-item value="Cars">Cars</sa-segmented-control-item>
    </sa-segmented-control>
</sa-stack>

Accessibility

The outer element is a div with role="radiogroup". Each item renders a label containing a visually hidden native radio. Supply aria-label or aria-labelledby for unbound groups without a label, and visible text for every item. Label content may include decorative icons, but should not contain links, buttons, or other interactive controls.

Tab enters and leaves the group; arrow keys move between enabled options using the browser's native radio behavior. Space selects a focused option. The visible segment displays keyboard focus, and form reset restores the initial selection.

API reference

<sa-segmented-control>

Standard id, class, aria-*, and data-* attributes apply to the outer group. The component has one horizontal appearance matching the default tabs variant in the selected theme.

<sa-segmented-control-item>

Standard id and class attributes apply to the visible label. Each radio receives its own generated ID.