0
# React Switch
1

2
React Switch is a draggable toggle-switch component for React applications with extensive customization options. It provides an accessible, touch-friendly toggle control with smooth animations, custom styling capabilities, and zero-configuration default styling using inline styles.
3

4
## Package Information
5

6
- **Package Name**: react-switch
7
- **Package Type**: npm
8
- **Language**: JavaScript/JSX with TypeScript definitions
9
- **Installation**: `npm install react-switch`
10

11
## Core Imports
12

13
```javascript
14
import Switch from "react-switch";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const Switch = require("react-switch");
21
```
22

23
## Basic Usage
24

25
```javascript
26
import React, { useState } from "react";
27
import Switch from "react-switch";
28

29
function MyComponent() {
30
  const [checked, setChecked] = useState(false);
31

32
  const handleChange = (checked) => {
33
    setChecked(checked);
34
  };
35

36
  return (
37
    <label>
38
      <span>Enable notifications</span>
39
      <Switch onChange={handleChange} checked={checked} />
40
    </label>
41
  );
42
}
43
```
44

45
## Capabilities
46

47
### ReactSwitch Component
48

49
The main and only export from the package. A fully-featured toggle switch component with drag support, customizable appearance, and built-in accessibility features.
50

51
```typescript { .api }
52
declare class ReactSwitch extends React.Component<ReactSwitchProps & AllowedHTMLInputProps> {}
53

54
interface ReactSwitchProps {
55
  /** The checked state of the switch. If true, the switch is set to checked. If false, it is not checked. */
56
  checked: boolean;
57
  
58
  /** 
59
   * Invoked when the user clicks or drags the switch.
60
   * checked describes the presumed future state of the checked prop.
61
   * event is a native MouseEvent when the handle is clicked or dragged, and a SyntheticEvent at all other times.
62
   * id is the ID prop of the switch.
63
   */
64
  onChange: (
65
    checked: boolean,
66
    event: React.SyntheticEvent<MouseEvent | KeyboardEvent> | MouseEvent,
67
    id: string
68
  ) => void;
69
  
70
  /** When true, the switch will no longer be interactive and its colors will be greyed out. */
71
  disabled?: boolean;
72
  
73
  /** The switch will take on this color when it is not checked. Only accepts 3 or 6 digit hex colors, e.g., #888, #45abcd. Defaults to #888. */
74
  offColor?: string;
75
  
76
  /** The switch will take on this color when it is checked. Only accepts 3 or 6 digit hex colors, e.g., #080, #45abcd. Defaults to #080. */
77
  onColor?: string;
78
  
79
  /** The color of the handle of the switch when not checked. Only accepts 3 or 6 digit hex colors, e.g., #fff, #45abcd. Defaults to #fff. */
80
  offHandleColor?: string;
81
  
82
  /** The color of the handle of the switch when checked. Only accepts 3 or 6 digit hex colors, e.g., #fff, #45abcd. Defaults to #fff. */
83
  onHandleColor?: string;
84
  
85
  /** The diameter of the handle, measured in pixels. By default it will be slightly smaller than the height of the switch. */
86
  handleDiameter?: number;
87
  
88
  /** Icon to display on the handle while switch is unchecked. */
89
  uncheckedHandleIcon?: JSX.Element;
90
  
91
  /** Icon to display on the handle while switch is checked. */
92
  checkedHandleIcon?: JSX.Element;
93
  
94
  /** An icon that will be shown on the switch when it is not checked. Set to false to show no icon. Defaults to an x icon. */
95
  uncheckedIcon?: JSX.Element | boolean;
96
  
97
  /** An icon that will be shown on the switch when it is checked. Set to false to show no icon. Defaults to a checked icon. */
98
  checkedIcon?: JSX.Element | boolean;
99
  
100
  /** The box-shadow of the handle of the switch. */
101
  boxShadow?: string;
102
  
103
  /** The box-shadow of the handle of the switch when it is active or focused. Do not set this to null as it is important for accessibility. Defaults to '0px 0px 2px 3px #33bbff'. */
104
  activeBoxShadow?: string;
105
  
106
  /** The height of the background of the switch, measured in pixels. Defaults to 28. */
107
  height?: number;
108
  
109
  /** The width of the background of the switch, measured in pixels. Defaults to 56. */
110
  width?: number;
111
  
112
  /** Border radius of the switch and the handle. */
113
  borderRadius?: number;
114
  
115
  /** The className of the outer shell of the switch. */
116
  className?: string;
117
  
118
  /** The id of the embedded checkbox. */
119
  id?: string;
120
}
121

122
type AllowedHTMLInputProps = Omit<
123
  React.DetailedHTMLProps<React.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>,
124
  "onFocus" | "onBlur" | "onKeyUp" | "onChange" | "ref" | keyof ReactSwitchProps
125
>;
126
```
127

128
**Usage Examples:**
129

130
```javascript
131
import React, { useState } from "react";
132
import Switch from "react-switch";
133

134
// Basic usage
135
function BasicSwitch() {
136
  const [checked, setChecked] = useState(false);
137
  
138
  return (
139
    <Switch
140
      onChange={setChecked}
141
      checked={checked}
142
    />
143
  );
144
}
145

146
// Customized appearance
147
function CustomSwitch() {
148
  const [enabled, setEnabled] = useState(true);
149
  
150
  return (
151
    <Switch
152
      onChange={setEnabled}
153
      checked={enabled}
154
      onColor="#86d3ff"
155
      onHandleColor="#2693e6"
156
      handleDiameter={30}
157
      uncheckedIcon={false}
158
      checkedIcon={false}
159
      boxShadow="0px 1px 5px rgba(0, 0, 0, 0.6)"
160
      activeBoxShadow="0px 0px 1px 10px rgba(0, 0, 0, 0.2)"
161
      height={20}
162
      width={48}
163
      className="react-switch"
164
      id="material-switch"
165
    />
166
  );
167
}
168

169
// With custom icons
170
function IconSwitch() {
171
  const [darkMode, setDarkMode] = useState(false);
172
  
173
  return (
174
    <Switch
175
      onChange={setDarkMode}
176
      checked={darkMode}
177
      checkedIcon={<span style={{ color: 'white', fontSize: '12px' }}>🌙</span>}
178
      uncheckedIcon={<span style={{ color: 'white', fontSize: '12px' }}>☀️</span>}
179
      onColor="#4a5568"
180
      offColor="#e2e8f0"
181
    />
182
  );
183
}
184

185
// Disabled state
186
function DisabledSwitch() {
187
  const [value, setValue] = useState(false);
188
  
189
  return (
190
    <Switch
191
      onChange={setValue}
192
      checked={value}
193
      disabled={true}
194
    />
195
  );
196
}
197

198
// With form integration
199
function FormSwitch() {
200
  const [formData, setFormData] = useState({ notifications: false });
201
  
202
  const handleSwitchChange = (checked, event, id) => {
203
    setFormData({ ...formData, [id]: checked });
204
  };
205
  
206
  return (
207
    <form>
208
      <label htmlFor="notifications-switch">
209
        <span>Email notifications</span>
210
        <Switch
211
          onChange={handleSwitchChange}
212
          checked={formData.notifications}
213
          id="notifications"
214
          name="notifications"
215
          aria-label="Toggle email notifications"
216
        />
217
      </label>
218
    </form>
219
  );
220
}
221
```
222

223
### Default Values
224

225
```typescript { .api }
226
const defaultProps = {
227
  disabled: false,
228
  offColor: "#888",
229
  onColor: "#080",
230
  offHandleColor: "#fff",
231
  onHandleColor: "#fff",
232
  uncheckedIcon: /* Default X SVG icon */,
233
  checkedIcon: /* Default checkmark SVG icon */,
234
  boxShadow: null,
235
  activeBoxShadow: "0 0 2px 3px #3bf",
236
  height: 28,
237
  width: 56
238
};
239
```
240

241
## Key Features
242

243
- **Draggable Interface**: Supports mouse and touch drag operations for intuitive interaction
244
- **Accessibility**: Built-in keyboard navigation, screen reader support, and proper ARIA attributes
245
- **Customization**: Extensive styling options including colors, sizes, icons, and shadows
246
- **Zero Dependencies**: No external CSS required - uses inline styles for zero-configuration setup  
247
- **Type Safety**: Full TypeScript definitions included for enhanced developer experience
248
- **Browser Support**: Works with React 15.3.0+ through React 18+ across modern browsers
249
- **Small Bundle**: Under 2.5kB gzipped for minimal impact on application size
250
- **Animation**: Smooth CSS transitions for state changes and drag interactions
251

252
## Accessibility Features
253

254
The component includes several accessibility features:
255

256
- Uses a semantic checkbox input with `role="switch"`
257
- Supports keyboard navigation (Space/Enter to toggle)
258
- Provides appropriate `aria-checked` state
259
- Maintains focus management with visual focus indicators
260
- Screen reader compatible with proper labeling support
261

262
## Browser Compatibility
263

264
- Supports all modern browsers
265
- Mobile touch support for iOS and Android
266
- Requires React 15.3.0 or higher
267
- Uses CSS transitions and transforms for animations