Switch

Switch is an input field for toggling a single setting on or off.

When to Use
Basic Features
Read-Only & Disabled
Validation
Accessibility
Best Practices
Related Components

Switch is an input field for toggling a single setting on or off.

Note

Preview Feature

This is a preview version of Switch. You need to enable it with the feature flag com.vaadin.experimental.switchComponent. Preview versions may lack some planned features, and breaking changes may be introduced in any Vaadin version. We encourage you to try it out and provide feedback in the Forum so that we can make it stable. You can report bugs and request additional features on GitHub.

Open in a
new tab

Source code

SwitchBasic.javapackage com.vaadin.demo.component.switchcomponent;

import com.vaadin.flow.component.checkbox.Switch;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.router.Route;

@Route("switch-basic")
public class SwitchBasic extends Div {

    public SwitchBasic() {
        // tag::snippet[]
        Switch notifications = new Switch("Notifications");

        add(notifications);
        // end::snippet[]
    }

}
switch-basic.tsximport React from 'react';
import { Switch } from '@vaadin/react-components/Switch.js';

function Example() {
  return (
    // tag::snippet[]
    <Switch label="Notifications" />
    // end::snippet[]
  );
}

switch-basic.tsimport '@vaadin/switch';
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import { applyTheme } from 'Frontend/demo/theme';

@customElement('switch-basic')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-switch label="Notifications"></vaadin-switch>
      <!-- end::snippet[] -->
    `;
  }
}

A Switch presents a single setting as a track with a sliding marker. It’s toggled by clicking the graphic or the label, or by pressing Space while it’s focused, and it defaults to off when no value is set.

When to Use

Use a Switch to show whether a setting, feature, or mode is on — "Notifications", "Autosave", "Two-factor authentication". Its state is meaningful on its own, independently of the other fields on the page, and users expect toggling it to take effect immediately.

Use a Checkbox to mark a selection, such as picking an item, including a row, or agreeing to terms; those values are normally submitted with the rest of a form. A Checkbox also supports indeterminate state, which Switch doesn’t have.

Basic Features

The following features, common to most input field components, are supported:

Label

The label is used to identify the input field. It supports plain-text content. In the Lumo theme its length is limited to the width of the field (and truncated with ellipsis), while in the Aura theme labels wrap to multiple lines. Helpers and Tooltips can be used to provide additional information that doesn’t fit into the label.

Visible labels are strongly recommended for all input fields. In cases where the built-in label cannot be used, an external element can be associated as the field’s label through the aria-labelledby attribute (setAriaLabelledBy in Flow). Fields without any visible label should include an invisible label for assistive technologies with the aria-label attribute (setAriaLabel in Flow).

Helper

Helpers are used to provide additional information that the user may need to enter in the field, such as format requirements or explanations of the field’s purpose below the field.

A style variant is available for rendering the helper above the field.

In addition to plain text, helpers can contain components and HTML elements. However, complex and interactive content is likely to have accessibility issues.

External & Invisible Labels (ARIA)

Visible labels are strongly recommended for all input fields. In situations where the built-in label cannot be used, an external element can be associated as the field’s label through its element id. Fields without any visible label should be provided an invisible label for assistive technologies like screen readers.

Source code

HTML<!-- Associates external element as label: -->
<label id="external-label">This is the label</label>
<vaadin-switch accessible-name-ref="external-label">...

<!-- Invisible label for screen readers: -->
<vaadin-switch accessible-name="This is the label">...
Java// Associates external element as label:
NativeLabel label = new NativeLabel("This is the label");
label.setId("external-label");
field.setAriaLabelledBy("external-label");

// Invisible label for screen readers:
field.setAriaLabel("This is the label");

Open in a
new tab

Source code

SwitchBasicFeatures.javapackage com.vaadin.demo.component.switchcomponent;

import com.vaadin.flow.component.checkbox.Switch;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.router.Route;

@Route("switch-basic-features")
public class SwitchBasicFeatures extends Div {

    public SwitchBasicFeatures() {
        // tag::snippet[]
        Switch autosave = new Switch("Autosave");
        autosave.setHelperText("Automatically save changes as you work");
        autosave.setTooltipText("Last saved 5 minutes ago");

        add(autosave);
        // end::snippet[]
    }

}
switch-basic-features.tsximport React from 'react';
import { Switch } from '@vaadin/react-components/Switch.js';
import { Tooltip } from '@vaadin/react-components/Tooltip.js';

function Example() {
  return (
    // tag::snippet[]
    <Switch label="Autosave" helperText="Automatically save changes as you work">
      <Tooltip slot="tooltip" text="Last saved 5 minutes ago" />
    </Switch>
    // end::snippet[]
  );
}

switch-basic-features.tsimport '@vaadin/switch';
import '@vaadin/tooltip';
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import { applyTheme } from 'Frontend/demo/theme';

@customElement('switch-basic-features')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-switch label="Autosave" helper-text="Automatically save changes as you work">
        <vaadin-tooltip slot="tooltip" text="Last saved 5 minutes ago"></vaadin-tooltip>
      </vaadin-switch>
      <!-- end::snippet[] -->
    `;
  }
}

Read-Only & Disabled

Fields used to display values should be set to read-only mode to prevent editing. Read-only fields are focusable and visible to screen readers. They can display tooltips. Their values can be selected and copied.

Fields that are currently unavailable should be disabled. The reduced contrast of disabled fields makes them inappropriate for displaying information. They can’t be focused or display tooltips. They’re invisible to screen readers, and their values cannot be selected and copied.

Disabled fields can be useful in situations where they can become enabled based on some user action. Consider hiding fields entirely if there’s nothing the user can do to make them editable.

For a setting that the user can see but not change — one locked by a plan, a policy, or a parent setting — read-only is preferable to disabled. A read-only Switch remains focusable and announced, and it still accepts programmatic changes, so the application can toggle it for a system-driven update.

Open in a
new tab

Source code

SwitchReadonlyAndDisabled.javapackage com.vaadin.demo.component.switchcomponent;

import com.vaadin.flow.component.checkbox.Switch;
import com.vaadin.flow.component.orderedlayout.VerticalLayout;
import com.vaadin.flow.router.Route;

@Route("switch-readonly-and-disabled")
public class SwitchReadonlyAndDisabled extends VerticalLayout {

    public SwitchReadonlyAndDisabled() {

        // tag::snippet[]
        Switch auditLog = new Switch("Audit log retention (90 days)");
        auditLog.setValue(true);
        auditLog.setReadOnly(true);
        auditLog.setHelperText("Included on the Business plan");

        Switch dailyDigest = new Switch("Daily digest");
        dailyDigest.setEnabled(false);

        add(auditLog, dailyDigest);
        // end::snippet[]
    }

}
switch-readonly-and-disabled.tsximport React from 'react';
import { Switch } from '@vaadin/react-components/Switch.js';
import { VerticalLayout } from '@vaadin/react-components/VerticalLayout.js';

function Example() {
  return (
    <VerticalLayout theme="spacing">
      {/* tag::snippet[] */}
      <Switch
        label="Audit log retention (90 days)"
        helperText="Included on the Business plan"
        readonly
        checked
      />

      <Switch label="Daily digest" disabled />
      {/* end::snippet[] */}
    </VerticalLayout>
  );
}

switch-readonly-and-disabled.tsimport '@vaadin/switch';
import '@vaadin/vertical-layout';
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import { applyTheme } from 'Frontend/demo/theme';

@customElement('switch-readonly-and-disabled')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <vaadin-vertical-layout theme="spacing">
        <!-- tag::snippet[] -->
        <vaadin-switch
          label="Audit log retention (90 days)"
          helper-text="Included on the Business plan"
          readonly
          checked
        ></vaadin-switch>

        <vaadin-switch label="Daily digest" disabled></vaadin-switch>
        <!-- end::snippet[] -->
      </vaadin-vertical-layout>
    `;
  }
}

Validation

Switch supports a single constraint: it can be marked as required, in which case off is invalid and on is valid. This suits a setting that has to stay on, such as one enforced by a security policy. For a consent that the user has to accept before proceeding, use a Checkbox instead.

Required

Required fields are marked with an indicator next to the label, and become invalid if their value is first entered and then cleared.

An instruction text at the top of the form explaining the required indicator is recommended. The indicator itself can be customized with the --vaadin-input-field-required-indicator style property.

A required Switch isn’t shown as invalid until the user has toggled it, or the application triggers validation, so no error appears before the user has acted. Toggling the switch back on clears the invalid state immediately. Turn off the switch to see the validation message.

Open in a
new tab

Source code

SwitchValidation.javapackage com.vaadin.demo.component.switchcomponent;

import com.vaadin.flow.component.checkbox.Switch;
import com.vaadin.flow.component.checkbox.Switch.SwitchI18n;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.router.Route;

@Route("switch-validation")
public class SwitchValidation extends Div {

    public SwitchValidation() {
        // tag::snippet[]
        Switch twoFactor = new Switch("Two-factor authentication");
        twoFactor.setValue(true);
        twoFactor.setRequiredIndicatorVisible(true);
        twoFactor.setI18n(new SwitchI18n().setRequiredErrorMessage(
                "Required by your workplace security policy"));
        // end::snippet[]

        add(twoFactor);
    }

}
switch-validation.tsximport React from 'react';
import { Switch } from '@vaadin/react-components/Switch.js';

function Example() {
  return (
    // tag::snippet[]
    <Switch
      label="Two-factor authentication"
      required
      checked
      errorMessage="Required by your workplace security policy"
    />
    // end::snippet[]
  );
}

switch-validation.tsimport '@vaadin/switch';
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import { applyTheme } from 'Frontend/demo/theme';

@customElement('switch-validation')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-switch
        label="Two-factor authentication"
        required
        checked
        error-message="Required by your workplace security policy"
      ></vaadin-switch>
      <!-- end::snippet[] -->
    `;
  }
}

Note	The required indicator is visible only when the Switch has a label.

Note	Data Binding & Custom Validation Flow and Hilla offer an advanced API called Binder that allows you to bind data and add custom validation rules for multiple fields, creating forms. You can learn more about Binder from the corresponding Flow and Hilla articles.

Accessibility

Switch uses the WAI-ARIA switch role, so screen readers announce it as a switch and read its state as on or off, rather than as a checkbox that is checked or unchecked. The accessible state is kept in sync with the visible state at all times, whether the user toggles the switch, the application updates it programmatically, or a form resets it.

The label, helper, and error message are all associated with the control for assistive technologies, and the read-only and required states are announced as well.

Best Practices

Apply a switch’s change as soon as it’s toggled. A Switch can take part in a form that’s saved with a Save button — a settings form is a common case — but users expect a switch to apply right away.

Use short, descriptive labels with positive wording that name the setting being turned on — for example, "Notifications" rather than "Disable notifications". Negated labels make the off position ambiguous.

Avoid combining read-only with required on a switch that’s off, since that leaves the form in a state the user can’t correct.

Component	Usage Recommendation
Checkbox	Marks a selection — picking an item, agreeing to terms, or including a row — and supports an indeterminate state. See When to Use for choosing between the two.
Radio Button Group	Picks one of two or more equal options. Use a Switch when one value is clearly the "off" state of a feature, and a two-option radio group when both values are equal labels, such as "Imperial" and "Metric".
Select	Presents options in an overlay. Prefer a Select over a Switch only when the two values need long labels; a Switch shows both states at once and toggles in a single click.

Component

Usage Recommendation

Checkbox

Marks a selection — picking an item, agreeing to terms, or including a row — and supports an indeterminate state. See When to Use for choosing between the two.

Radio Button Group

Picks one of two or more equal options. Use a Switch when one value is clearly the "off" state of a feature, and a two-option radio group when both values are equal labels, such as "Imperial" and "Metric".

Select

Presents options in an overlay. Prefer a Select over a Switch only when the two values need long labels; a Switch shows both states at once and toggles in a single click.

Docs

Docs

Switch

When to Use

Basic Features

Read-Only & Disabled

Validation

Accessibility

Best Practices

Docs

When to Use

Basic Features

Read-Only & Disabled

Validation

Accessibility

Best Practices

Related Components