Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/markusenglund/react-switch
A draggable toggle-switch component for React. Check out the demo at:
https://github.com/markusenglund/react-switch
Last synced: about 2 months ago
JSON representation
A draggable toggle-switch component for React. Check out the demo at:
- Host: GitHub
- URL: https://github.com/markusenglund/react-switch
- Owner: markusenglund
- License: mit
- Created: 2017-09-15T17:32:20.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2023-12-12T13:34:38.000Z (10 months ago)
- Last Synced: 2024-07-18T12:11:41.990Z (2 months ago)
- Language: JavaScript
- Homepage: https://react-switch.netlify.com/
- Size: 1.96 MB
- Stars: 1,325
- Watchers: 9
- Forks: 101
- Open Issues: 36
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
A draggable toggle-switch component for React.
[](https://www.npmjs.com/package/react-switch)
[](https://www.npmjs.com/package/react-switch)
[](https://github.com/markusenglund/react-switch)
[](https://unpkg.com/react-switch/dist/react-switch.min.js)
- **Draggable** with the mouse or with a touch screen.
- **Customizable** - Easy to customize size, color and more.
- **Accessible** to visually impaired users and those who can't use a mouse.
- **Reasonable package size** - <2.5 kB gzipped.
- **It Just Works** - Sensible default styling. Uses inline styles, so no need to import a separate css file.
## Demo
[Take a look at the demo](https://react-switch.netlify.com/)
## Installation
```bash
npm install react-switch
```
## Usage
```javascript
import React, { Component } from "react";
import Switch from "react-switch";
class SwitchExample extends Component {
constructor() {
super();
this.state = { checked: false };
this.handleChange = this.handleChange.bind(this);
}
handleChange(checked) {
this.setState({ checked });
}
render() {
return (
Switch with default style
);
}
}
```
### What's the deal with the label tag?
The Switch component in the above example is nested inside a label tag. This makes sure that the label text is read out to people with reduced sight who use screen readers and enables users to click on the text to toggle the switch. If you would only put some text next to the switch but not inside a `label` element, the screen reader will just read out "switch off" and the user will have no idea what it is for.
If you don't want to nest the switch inside a label, you can use the `htmlFor` attribute on the label-element and set it to the same value as the `id` of the switch. Alternatively, you can use the `aria-labelledby` or `aria-label` props to give the switch a label. You can see examples of this at the bottom of the [demo page](https://react-switch.netlify.com/).
## API
| Prop | Type | Default | Description |
| ------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| checked | bool | **Required** | If true, the switch is set to checked. If false, it is not checked. |
| onChange _([checked], [event], [id])_ | func | **Required** | Invoked when the user clicks or drags the switch. It is passed three arguments: _checked_, which is a boolean that describes the presumed future state of the checked prop (1), the event object (2) and the id prop (3). |
| disabled | bool | false | When disabled, the switch will no longer be interactive and its colors will be greyed out. |
| offColor | string | '#888' | The switch will take on this color when it is _not_ checked. Only accepts hex-colors. |
| onColor | string | '#080' | The switch will take on this color when it is checked. Only accepts hex-colors. |
| offHandleColor | string | '#fff' | The handle of the switch will take on this color when it is _not_ checked. Only accepts hex-colors. |
| onHandleColor | string | '#fff' | The handle of the switch will take on this color when it is checked. Only accepts hex-colors. |
| handleDiameter | number | _undefined_ | The diameter of the handle, measured in pixels. By default it will be 2 pixels smaller than the height of the switch. |
| uncheckedIcon | element _or_ bool | [Default value](https://github.com/markusenglund/react-switch/blob/master/src/icons.jsx) | An icon that will be shown on the switch when it is **not** checked. Pass in _false_ if you don't want any icon. |
| checkedIcon | element _or_ bool | [Default value](https://github.com/markusenglund/react-switch/blob/master/src/icons.jsx) | An icon that will be shown on the switch when it is checked. Pass in _false_ if you don't want any icon. |
| uncheckedHandleIcon | element | _undefined_ | An icon that will be shown on **the handle** of the switch when it is **not** checked. |
| checkedHandleIcon | element | _undefined_ | An icon that will be shown on **the handle** of the switch when it is checked. |
| boxShadow | string | _undefined_ | The default box-shadow of the handle. You can read up on the box-shadow syntax [on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/box-shadow?v=b). |
| activeBoxShadow | string | '0 0 2px 3px #3bf' | The box-shadow of the handle when it is active or focused. Do not set this to null, since it is important for accessibility. |
| height | number | 28 | The height of the background of the switch, measured in pixels. |
| width | number | 56 | The width of the background of the switch, measured in pixels. |
| className | string | _undefined_ | Set as the className of the outer shell of the switch. Useful for positioning the switch. |
| borderRadius | number | _undefined_ | Border radius of the switch _and_ the handle. |
| id | string | _undefined_ | Set as an attribute to the embedded checkbox. This is useful for the associated label, which can point to the id in its htmlFor attribute. |
---
**NOTE**: All additional props will be passed to the nested `input` element.
The following props have to be either 3-digit or 6-digit hex-colors:
**offColor, onColor, offHandleColor,** and **onHandleColor.** This is because this library calculates intermediate color values based on the hex-color strings.
Examples of valid colors: '#abc', '#123456'
Examples of **invalid** colors: 'red', 'rgb(0,0,0)'
## Development
You're welcome to contribute to react-switch. Keep in mind that big changes have to be thoroughly tested on lots of different browsers and devices before they can be merged.
To set up the project:
1. Fork and clone the repository
2. `$ npm install`
3. `$ npm run dev`
The demo page will then be served on http://localhost:8000/ in watch mode, meaning you don't have refresh the page to see your changes.
## Contributors
## License
MIT
