Switch Component

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

Live Demo

Anatomy

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

The following diagram shows the logical structure of the Angular 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 Angular Switch, follow the Ignite UI for Angular Getting Started topic for the basic project setup, then register the component for your target platform.

At its core, the Switch 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 Angular using the igniteui-angular package, install the package:

npm install igniteui-angular

Then import the IgxSwitchComponent:

import { IgxSwitchComponent } from 'igniteui-angular/switch';

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

<igx-switch [checked]="true">Simple switch</igx-switch>

Usage

Use the Angular 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:

<igx-switch>Accept terms</igx-switch>

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

<igx-switch [required]="true">Label</igx-switch>

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

<igx-switch [invalid]="true">Label</igx-switch>

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.

<igx-switch [disabled]="true">Label</igx-switch>

On/Off States

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

<igx-switch [checked]="true">On</igx-switch>
<igx-switch [checked]="false">Off</igx-switch>

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):

<igx-switch labelPosition="before">Label</igx-switch>

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.

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

Styling

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

Sass Theming

To get started with styling the switch, import the index file, where all the theme functions and the tokens() mixin are exported:

@use "igniteui-angular/theming" as *;

Then create a new theme that extends switch-theme. Providing $thumb-off-color and $thumb-on-color is enough to get a fully styled switch, because the theme generates the remaining colors from them:

$custom-switch-theme: switch-theme(
    $thumb-off-color: #7cadd5,
    $thumb-on-color: #ecaa53,
);

Finally, include the custom theme in your application:

:host {
  @include tokens($custom-switch-theme);
}

Styling with Tailwind

You can style the switch using the Ignite UI Tailwind utility classes. Make sure to set up Tailwind first, then import the utility file in your global stylesheet:

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

Use light-switch or dark-switch for the corresponding theme and override the generated CSS variables with arbitrary properties. You can find the full list of properties in the IgxSwitch Theme:

<igx-switch
  class="!light-switch ![--thumb-on-color:#FF4E00]"
  [checked]="true">
  Label
</igx-switch>

The exclamation mark (!) makes the utility class important so it takes precedence over the component theme.

Accessibility

The Angular 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.

Accessibility Compliance

Infragistics documents Ignite UI for Angular 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 Angular 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 Angular Switch requires a theme stylesheet to apply its visual styling. See the framework-specific setup in Getting Started.

Additional Resources

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

• Lists - Design System Pattern
• Ignite UI for Angular Forums
• Ignite UI for Angular 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