React Switch Component

7.1.0 · active · verified Sun Apr 19

react-switch is a lightweight, customizable, and accessible toggle-switch component for React applications. Currently at version 7.1.0, it provides a draggable switch with sensible default styling that uses inline styles, eliminating the need for separate CSS imports. Key differentiators include its small bundle size (<2.5 kB gzipped), built-in accessibility features (with guidance on proper label usage), and high customizability for visual appearance. The library is actively maintained, though a specific release cadence isn't published. It supports a wide range of React versions, from 15.3.0 up to 19.0.0, as specified in its peer dependencies, making it compatible with both older and very recent React projects.

Common errors

```
Warning: Failed prop type: The prop `checked` is marked as required in `Switch`, but its value is `undefined`.
```
cause The `checked` prop was not provided or was `undefined` when the `Switch` component rendered.

fix Provide a boolean value for the `checked` prop, typically from component state: `checked={this.state.isChecked}`.
```
Warning: You provided a `checked` prop to a form field without an `onChange` handler. This will render a read-only field. If the field should be mutable use `defaultChecked`. Otherwise, set either `onChange` or `readOnly`.
```
cause A `Switch` component was rendered as a controlled component (with `checked` prop) but lacked an `onChange` handler to update its state.

fix Add an `onChange` handler to the `Switch` component that updates the state controlling the `checked` prop: `onChange={this.handleChange}`.
```
Screen reader only announces 'switch off' without context.
```
cause The `Switch` component is not properly associated with a descriptive label for assistive technologies.

fix Wrap the `Switch` and its descriptive text within a `<label>` tag or use `htmlFor` and `id` attributes to link them, or `aria-label`/`aria-labelledby` props on the `Switch` itself.

Warnings

gotcha The `checked` and `onChange` props are both required for the `Switch` component to function as a controlled input. Omitting either will result in errors or unexpected behavior where the switch does not update or is read-only.
Fix: Ensure both `checked={this.state.someBoolean}` and `onChange={this.handleChange}` are passed to the `Switch` component, where `handleChange` updates the state tied to `checked`.
gotcha For proper accessibility, especially for screen reader users, the `Switch` component should be associated with a descriptive label. Nesting the switch within a `<label>` tag is the easiest method. Alternatively, use `htmlFor` with a matching `id`, or `aria-labelledby`/`aria-label` props on the `Switch`.
Fix: Wrap the `Switch` component and its descriptive text in a `<label>` element, or explicitly link them using `htmlFor`/`id` or `aria-label`/`aria-labelledby`.
breaking While the core API for `react-switch` remains largely stable, always review peer dependency updates in major versions. For example, `react-switch` v7 broadened its `react` and `react-dom` peer dependency to include `^19.0.0`, while maintaining compatibility with older React versions down to `^15.3.0`. Developers using older React versions might need to manage their `react` peer dependency to ensure compatibility with other libraries.
Fix: Verify that your `react` and `react-dom` versions satisfy the peer dependency requirements of `react-switch`. Update React or use an older `react-switch` version if necessary.

Install

npm install react-switch npm
yarn add react-switch yarn
pnpm add react-switch pnpm

Imports

Switch
wrong:
```
import { Switch } from 'react-switch';
```
correct:
```
import Switch from 'react-switch';
```
The primary component is exported as a default export.
SwitchProps
```
import type { SwitchProps } from 'react-switch';
```
Type definition for component props, for TypeScript users.
CommonJS require
```
const Switch = require('react-switch');
```
CommonJS import for older Node.js environments or build systems.

Quickstart

Demonstrates a basic controlled `Switch` component within a `label` for accessibility, handling state changes and customizable appearance.

import React, { Component } from "react";
import Switch from "react-switch";

class SwitchExample extends Component {
  constructor(props) {
    super(props);
    this.state = { checked: false };
    this.handleChange = this.handleChange.bind(this);
  }

  handleChange(checked) {
    this.setState({ checked });
  }

  render() {
    return (
      <label htmlFor="my-switch">
        <span>Toggle Feature</span>
        <Switch
          id="my-switch"
          onChange={this.handleChange}
          checked={this.state.checked}
          offColor="#ccc"
          onColor="#88b"
          height={24}
          width={48}
          handleDiameter={20}
          aria-label="Toggle feature on or off"
        />
      </label>
    );
  }
}

export default SwitchExample;

view raw JSON →