Switch

<sa-field orientation="FieldOrientation.Horizontal">
    <sa-switch id="intro-notifications" checked/>
    <sa-field-content>
        <sa-field-label for="intro-notifications">Flight alerts</sa-field-label>
        <sa-field-description>
            Receive an email when a flight on your itinerary changes.
        </sa-field-description>
    </sa-field-content>
</sa-field>

Usage

<sa-switch> renders a native checkbox styled as a switch. Because the underlying element is a checkbox, the switch posts its value back and model-binds like any other bool, while the on/off appearance is driven entirely by CSS — no JavaScript is required.

<sa-switch/>

Examples

Model binding

Supports ASP.NET Core model binding via asp-for. Bind it to a bool property and an unchecked switch will post false.

When using model binding, StellarAdmin will automatically wrap the switch inside a Field with the correct label and description derived from data attributes. You can opt out of this behavior by setting the render-field attribute to false.

<sa-switch asp-for="EmailNotifications"/>

Sizes

Use the size attribute to control the size of the switch. It accepts SwitchSize.Default (the default) and SwitchSize.Small.

<sa-field orientation="FieldOrientation.Horizontal">
    <sa-switch id="size-default" checked/>
    <sa-field-content>
        <sa-field-label for="size-default">Default</sa-field-label>
    </sa-field-content>
</sa-field>
<sa-field orientation="FieldOrientation.Horizontal">
    <sa-switch id="size-small" size="SwitchSize.Small" checked/>
    <sa-field-content>
        <sa-field-label for="size-small">Small</sa-field-label>
    </sa-field-content>
</sa-field>

Disabled

Add the disabled attribute to prevent the user from interacting with the switch.

<sa-field orientation="FieldOrientation.Horizontal">
    <sa-switch id="disabled-off" disabled/>
    <sa-field-content>
        <sa-field-label for="disabled-off">Off</sa-field-label>
    </sa-field-content>
</sa-field>
<sa-field orientation="FieldOrientation.Horizontal">
    <sa-switch id="disabled-on" disabled checked/>
    <sa-field-content>
        <sa-field-label for="disabled-on">On</sa-field-label>
    </sa-field-content>
</sa-field>

Accessibility

<sa-switch> renders a native <input type="checkbox"> with role="switch", so it is announced as a switch, focused with Tab and toggled with Space. With asp-for or the label attribute the label is wired to the input for you. When you write the label yourself, set its for attribute to the switch's id.

Part classes

Pass a SwitchClassNames instance from the StellarAdmin.TagHelpers namespace to <sa-switch> using class-names. Each property accepts an optional string of space-separated CSS classes, which are added to the part's existing classes.

@{
    var partClasses = new SwitchClassNames
    {
        Root = "travel-field",
        Label = "travel-label",
        Description = "travel-help",
        Control = "travel-switch-control",
    };
}

<sa-switch id="classes-alerts" label="Flight alerts" description="Receive updates when your itinerary changes." checked class-names="@partClasses" />

Root, Label, Description, Error, and Content are inherited from FieldClassNames. They only style generated field elements; with render-field="false", apply class directly to any field elements you compose yourself. The control-specific parts still apply. See Field part classes for the shared behavior and a styled example.

API Reference

<sa-switch>

Renders a native <input type="checkbox" role="switch"> wrapped in a <span> that hosts the thumb. When asp-for is set, it delegates to the built-in ASP.NET Core Input Tag Helper so the switch model-binds like any other bool.