Switch

A switch component allows a user to switch on or off form element.

Uncontrolled Value

By default, the Switch component handles its value uncontrolled. In the uncontrolled variant you can pass in a defaultSelected to set a value by default.

<Switch aria-label='Light bulb switch' defaultSelected />

<Switch aria-label='Light bulb switch' defaultSelected />

<Switch
  aria-label="Light bulb switch"
  defaultSelected
/>

Controlled Value

You can also handle the value of the component in a controlled manner. To do so, you can pass in a isSelected prop as well as an onChange handler to modify the value when the user types.

function Example() {
  const [selected, setSelection] = useState(true);

  return (
    <>
      <Switch
        aria-label='Light bulb switch'
        isSelected={selected} 
        onChange={setSelection} 
      />
      <div>The Switch is on: {selected.toString()}</div>
    </>
  );
}

function Example() {
  const [selected, setSelection] = useState(true);

  return (
    <>
      <Switch
        aria-label='Light bulb switch'
        isSelected={selected} 
        onChange={setSelection} 
      />
      <div>The Switch is on: {selected.toString()}</div>
    </>
  );
}

function Example() {
  const [
    selected,
    setSelection
  ] = useState(true);

  return (
    <>
      <Switch
        aria-label="Light bulb switch"
        isSelected={selected}
        onChange={setSelection}
      />
      <div>
        The Switch is on:
        {' '}
        {selected
          .toString()}
      </div>
    </>
  );
}

Labeling

A Switch component should be labeled with a visual text through the label prop. If the Switch does not include a textual label, an aria-label or aria-labelledby prop need to be provided to support assistive technology such as screen readers.

<Switch label='Light bulb switch' />

<Switch label='Light bulb switch' />

<Switch label="Light bulb switch" />

Label Position

By default, the label of the Switch component is displayed above the input. With the labelPlacement prop this placement can be adjusted to be on the side of the input.

<Switch label="Light bulb switch" labelPlacement="side end" />

<Switch
  label="Light bulb switch"
  labelPlacement="side end"
/>

<Switch
  label="Light bulb switch"
  labelPlacement="side end"
/>

Validation

The Switch component has built-in accessible validation support. To indicate whether the field is valid or not you can use the errorMessage prop.

function Example() {
  const [value, setValue] = useState(false);

  const errorMessage = !value
    ? 'You must turn it on to continue exploring the room'
    : undefined;

  return (
    <div>
      <Switch
        label="Light bulb switch"
        value={value}
        onChange={setValue}
        errorMessage={errorMessage}
      />
    </div>
  );
}

function Example() {
  const [value, setValue] = useState(false);

  const errorMessage = !value
    ? 'You must turn it on to continue exploring the room'
    : undefined;

  return (
    <div>
      <Switch
        label="Light bulb switch"
        value={value}
        onChange={setValue}
        errorMessage={errorMessage}
      />
    </div>
  );
}

function Example() {
  const [
    value,
    setValue
  ] = useState(false);

  const errorMessage =
    !value
      ? 'You must turn it on to continue exploring the room'
      : undefined;

  return (
    <div>
      <Switch
        label="Light bulb switch"
        value={value}
        onChange={setValue}
        errorMessage={errorMessage}
      />
    </div>
  );
}

Description

To give further instructions or more verbose examples to the user about a Switch you can provide a description prop. Avoid using error like tone of voice of the message. If an errorMessage prop is provided it will replace the description.

<Switch label="Light bulb switch" description="Turn it on or off" />

<Switch
  label="Light bulb switch"
  description="Turn it on or off"
/>

<Switch
  label="Light bulb switch"
  description="Turn it on or off"
/>

Contextual Help

To offer the user contextual help, the Switch supports passing a contextualHelp prop, that accepts a ReactNode.

<Switch 
  label='Light bulb switch' 
  contextualHelp={(
    <ContextualHelp variant="info">
      <Header>
        <Heading>Lorem Ipsum</Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
        </Text>
      </Content>
    </ContextualHelp>
  )} 
/>

<Switch
  label="Light bulb switch"
  contextualHelp={
    <ContextualHelp variant="info">
      <Header>
        <Heading>Lorem Ipsum</Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum dolor sit amet, consectetur
          adipiscing elit.
        </Text>
      </Content>
    </ContextualHelp>
  }
/>

<Switch
  label="Light bulb switch"
  contextualHelp={
    <ContextualHelp variant="info">
      <Header>
        <Heading>
          Lorem Ipsum
        </Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum
          dolor sit
          amet,
          consectetur
          adipiscing
          elit.
        </Text>
      </Content>
    </ContextualHelp>
  }
/>

Disabled

The Switch component can be disabled via the isDisabled prop.

<Switch label="Light bulb switch" isDisabled value={true} />

<Switch label="Light bulb switch" isDisabled value={true} />

<Switch
  label="Light bulb switch"
  isDisabled
  value={true}
/>

Accessibility

In order to support internationalization, provide a localized string to the label or aria-label prop.

API