Toggle

<sa-toggle aria-label="Save to wishlist">
    <sa-icon name="heart"/>
</sa-toggle>

Usage

<sa-toggle> renders a two-state button — useful for things like formatting toggles or filters. It is backed by a native checkbox, so it posts its value back and model-binds like any other bool, while the pressed appearance is driven entirely by CSS — no JavaScript is required.

Place an icon and/or text inside the Tag Helper to label the toggle.

<sa-toggle aria-label="Toggle bold">
    <sa-icon name="bold"/>
</sa-toggle>

Examples

Outline

Use the variant attribute to control the visual style of the toggle. It accepts ToggleVariant.Default (the default) and ToggleVariant.Outline.

<sa-toggle variant="ToggleVariant.Outline" aria-label="Show on map">
    <sa-icon name="map-pin"/>
</sa-toggle>

With text

A toggle can contain both an icon and a text label.

<sa-toggle variant="ToggleVariant.Outline" aria-label="Free Wi-Fi">
    <sa-icon name="wifi"/>
    Free Wi-Fi
</sa-toggle>

Sizes

Use the size attribute to control the size of the toggle. It accepts ToggleSize.Default (the default), ToggleSize.Small and ToggleSize.Large.

<sa-toggle size="ToggleSize.Small" variant="ToggleVariant.Outline" aria-label="Pool">
    <sa-icon name="waves"/>
</sa-toggle>
<sa-toggle size="ToggleSize.Default" variant="ToggleVariant.Outline" aria-label="Pool">
    <sa-icon name="waves"/>
</sa-toggle>
<sa-toggle size="ToggleSize.Large" variant="ToggleVariant.Outline" aria-label="Pool">
    <sa-icon name="waves"/>
</sa-toggle>

Disabled

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

<sa-toggle disabled aria-label="Pet friendly">
    <sa-icon name="dog"/>
</sa-toggle>
<sa-toggle variant="ToggleVariant.Outline" disabled checked aria-label="Pet friendly">
    <sa-icon name="dog"/>
</sa-toggle>

Model binding

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

Because a toggle is self-labelling, this example opts out of the automatic Field wrapper by setting the render-field attribute to false.

<sa-toggle asp-for="BreakfastIncluded" variant="ToggleVariant.Outline" render-field="false">
    <sa-icon name="coffee"/>
    Breakfast included
</sa-toggle>

Accessibility

<sa-toggle> renders a <label> wrapping a visually hidden native <input type="checkbox">, so it is focused with Tab, toggled with Space and announced as a checkbox with its checked state. The visible button shows the focus ring of the input inside it. Attributes you put on <sa-toggle>, including aria-label, are placed on the input.

An icon-only toggle has no accessible name. Give it one with aria-label.

API Reference

<sa-toggle>

Renders a <label> wrapping a visually hidden native <input type="checkbox"> that carries the on/off value. When asp-for is set, it delegates to the built-in ASP.NET Core Input Tag Helper so the toggle model-binds like any other bool.