Switch Component

The Ignite UI for Blazor Switch component is a binary choice selection component that behaves similarly to the switch component in iOS.

Live Demo

Anatomy

The Blazor Switch contains a control for changing a binary state and an optional label.

The following diagram shows the logical structure of the Blazor Switch. The control manages the binary state, while the optional label describes the setting controlled by the switch.

Switch
├── Control
└── Label (optional)

Getting Started

To use the Blazor Switch, follow the Ignite UI for Blazor Getting Started topic for the basic project setup, then register the component for your target platform.

At its core, the IgbSwitch component allows for toggling between on/off states. The default styling is done according to the selection controls specification in the Material Design guidelines.

For Blazor using the IgniteUI.Blazor package, register the Switch module as follows:

// in Program.cs file

builder.Services.AddIgniteUIBlazor(typeof(IgbSwitchModule));

Then link the additional CSS file in the wwwroot/index.html file for a Blazor WebAssembly project or in the Pages/_Host.cshtml file for a Blazor Server project:

<link href="_content/IgniteUI.Blazor/themes/light/bootstrap.css" rel="stylesheet" />

The simplest way to start using the IgbSwitch is as follows:

<IgbSwitch />

Usage

Use the Blazor Switch as a binary choice control for settings that take effect immediately when the user changes their state.

The following example shows the basic Switch configuration. To provide a meaningful label for the switch, simply place some text between the opening and closing tags:

<IgbSwitch>Accept terms</IgbSwitch>

You can use the required property to mark the switch as required.

<IgbSwitch Required="true" />

You can use the invalid property to mark the switch as invalid.

<IgbSwitch Invalid="true" />

Interaction States

The Switch can be inserted in an Enabled or Disabled state. In Enabled state, the switch also supports Hover, Focused and Focused & Hover states.

Disabled States

You may also set the state of the switch to Disabled to disallow user interaction with it. You can use the disabled attribute to set this state.

<IgbSwitch Disabled="true" />

On/Off States

The Switch can be set to an On or Off state to indicate whether a setting is enabled or disabled.

<IgbSwitch Checked="true">On</IgbSwitch>
<IgbSwitch Checked="false">Off</IgbSwitch>

Layout

You can specify if the label should be positioned before or after the switch toggle by setting the LabelPosition property of the switch. Allowed values are before and after (default):

<IgbSwitch LabelPosition="@ToggleLabelPosition.Before">Label</IgbSwitch>

The switch can also be labelled by elements external to the switch. In this case, the user is given full control to position and style the label in accordance with their needs.

<span id="switch-label">Label</span>
<IgbSwitch AriaLabelledBy="switch-label" />

Do/Don’t

When to use: Use Switch for an immediate on/off setting that takes effect when the user changes it.

When not to use: Use Checkbox when users select one or more options for a later form submission, or Button when the control represents an action or a toggleable command.

Do	Don’t

Properties

<IgbSwitch Name="wifi" Value="enabled" />

Styling

The Blazor Switch uses CSS parts and CSS variables to style its track, thumb, and label.

Sass Theming

Use the Ignite UI for Blazor theme system to style the Switch consistently with the rest of your application.

Import the theming functions before creating a custom Switch theme:

@use "igniteui-theming" as *;

Create a theme with switch-theme and include it in the global stylesheet. The track and thumb parameters are used as the base for the related interaction-state colors:

$custom-switch: switch-theme(
    $track-on-color: #57a5cd,
);

igc-switch {
    @include switch($custom-switch);
}

The same theme applies to Web Components directly and to the underlying igc-switch element rendered by the React and Blazor wrappers.

CSS Variables

Use the following CSS variables to customize the Switch colors and interaction states. Set them on the Switch element to apply the styles to its track, thumb, and label:

Style Parts

Use the following CSS parts to target the Switch and its inner elements:

Custom Styling

The following example changes the track and thumb colors for the checked and unchecked states:

igc-switch {
  --thumb-on-color: white;
  --thumb-off-color: var(--ig-success-500);
  --track-on-color: var(--ig-success-500); /* Background color when checked */
  --track-off-color: white; /* Background color when unchecked */
  --track-on-hover-color: var(--ig-success-500); /* Background hover color when checked */
}

Styling with Tailwind

You can style the Blazor Switch with the custom Tailwind utility classes from igniteui-theming. Make sure to set up Tailwind first, then import the Ignite UI utilities in your global stylesheet:

@import "tailwindcss";
@import "igniteui-theming/tailwind/utilities/material.css";

<IgbSwitch Class="!light-switch ![--track-on-color:#7B9E89]" />

The exclamation mark (!) gives the Tailwind utility precedence over the Switch’s default theme styles.

Accessibility

The Blazor Switch exposes a binary state and supports an accessible name through its label or ARIA attributes.

Keyboard Interaction

Screen Readers / ARIA

The Switch renders an interactive control with a binary checked state. Provide visible label content or an accessible name with aria-label or aria-labelledby, and keep the label specific to the setting controlled by the switch.

• The control exposes its checked state and disabled state to assistive technology.
• The igcChange event is emitted when the checked state changes.

Accessibility Compliance

Infragistics documents Ignite UI for Blazor accessibility support for Section 508 and WCAG 2.1 guideline areas in the Accessibility Compliance topic.

Troubleshooting

Use this section to check boundaries and common decisions before treating Switch as a form field, interactive command, or setting control.

Why does the Switch not submit with my form?

The Switch is form-associated but requires a name and value to contribute a value when the form is submitted. Set both properties and use the form integration supported by your target platform.

Why is the Switch not announced correctly by a screen reader?

The Switch needs an accessible name. Add visible label content or reference an external label with aria-labelledby; use aria-label when visible text is not available.

Known Limitations

The Blazor Switch has the following platform-independent limitations:

• A Switch represents one binary setting; use a different control when users need multiple choices or a deferred form selection.
• A Switch does not provide an accessible name automatically when it has no label or ARIA naming attribute.

API References

Dependencies

The Blazor Switch requires a theme stylesheet to apply its visual styling. See the framework-specific setup in Getting Started.

Additional Resources

Use the following Blazor resources for API details, examples, and project support:

• Lists - Design System Pattern
• Ignite UI for Blazor Forums
• Ignite UI for Blazor GitHub

Related Components

• Checkbox - Use Checkbox when users select one or more options, especially as part of a form.
• Button - Use Button when the control represents a command or action rather than a setting.

FAQ