react-toggled

by kentcdodds

kentcdodds /react-toggled

Component to build simple, flexible, and accessible toggle components

446 Stars 49 Forks Last release: over 2 years ago (v1.2.7) MIT License 23 Commits 15 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

react-toggled βš›οΈ
react-toggled logo

Component to build simple, flexible, and accessible toggle components


Build Status Code Coverage downloads version MIT License

All Contributors PRs Welcome Chat Code of Conduct

Supports React and Preact size gzip size module formats: umd, cjs, and es

Watch on GitHub Star on GitHub Tweet

The problem

You want a toggle component that's simple and gives you complete control over rendering and state.

This solution

This follows the patterns in

downshift
to expose an API that renders nothing and simply encapsulates the logic of a toggle component.

Table of Contents

Installation

This module is distributed via npm which is bundled with node and should be installed as one of your project's

dependencies
:
npm install --save react-toggled

This package also depends on

react
and
prop-types
. Please make sure you have those installed as well.

Note also this library supports

preact
out of the box. If you are using
preact
then look in the
preact/
folder and use the module you want. You should be able to simply do:
import Toggle from 'react-toggled/preact'

Usage

import React from 'react'
import {render} from 'react-dom'
import Toggle from 'react-toggled'

render( {({on, getTogglerProps}) => (

Toggle me
{on ? 'Toggled On' : 'Toggled Off'}
)} , document.getElementById('root'), )

react-toggled
is the only component. It doesn't render anything itself, it just calls the child function and renders that. Wrap everything in
{/* your function here! */}
.

Props:

defaultOn

boolean
| defaults to
false

The initial

on
state.

onToggle

function(on: boolean, object: TogglerStateAndHelpers)
| optional, no useful default

Called when the toggler is clicked.

  • on
    : The new on state
  • TogglerStateAndHelpers
    : the exact same thing you get in your child render prop function.

on

boolean
| control prop

react-toggled manages its own state internally and calls your

onToggle
handler whenever the
on
state changes. Your child render prop function (read more below) can be used to manipulate this state from within the render function and can likely support many of your use cases.

However, if more control is needed, you can pass the

on
state as a prop and that state becomes controlled. As soon as
this.props.on !== undefined
, internally,
react-toggled
will determine its state based on your prop's value rather than its own internal state. You will be required to keep the state up to date (this is where
onToggle
comes in really handy), but you can also control the state from anywhere, be that state from other components,
redux
,
react-router
, or anywhere else.

Note: This is very similar to how normal controlled components work elsewhere in react (like

). If you want to learn more about this concept, you
can learn about that from this the
"Controlled Components" lecture and
exercises from React Training's > Advanced React course.

children

function({})
| required

This is called with an object.

This is where you render whatever you want to based on the state of

react-toggled
. The function is passed as the child prop:
{/* right here*/}

| property | category | type | description | | ------------------------ | ----------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | |

on
| state |
boolean
| The current
on
state of toggle | |
getTogglerProps
| prop getter |
function(props: object)
| returns the props you should apply to the button element you render. Includes
aria-
attributes | |
getInputTogglerProps
| prop getter |
function(props: object)
| returns the props you should apply to the input (checkbox) element you render. Includes
aria-
attributes | |
getElementTogglerProps
| prop getter |
function(props: object)
| returns the props you should apply to the element you render. Use this if you are not using a button or inputβ€”for example, a span. Includes
aria-
attributes | |
setOn
| action |
function()
| Sets the
on
state to
true
| |
setOff
| action |
function()
| Sets the
on
state to
false
| |
toggle
| action |
function()
| Toggles the
on
state (i.e. if it's currently
true
, will set to
false
) |

Examples

Examples exist on codesandbox.io:

If you would like to add an example, follow these steps:

  1. Fork this codesandbox
  2. Make sure your version (under dependencies) is the latest available version.
  3. Update the title and description
  4. Update the code for your example (add some form of documentation to explain what it is)
  5. Add the tag:
    react-toggled:example

You'll find other examples in the

stories/examples
folder of the repo. And you'll find a live version of those examples here

Inspiration

I built this while building an example of using

glamorous
with
next.js

Other Solutions

You can implement any of the other solutions using

react-toggled
, but if you'd prefer to use these out of the box solutions, then that's fine too. There are tons of them, so just checkout npm.

Contributors

Thanks goes to these people (emoji key):

Kent C. Dodds
Kent C. Dodds

πŸ’» πŸ“– πŸš‡ ⚠️
Frank Tan
Frank Tan

πŸ’» πŸ“– ⚠️
Oliver
Oliver

πŸ’»
Jedrzej Lewandowski
Jedrzej Lewandowski

πŸ’»
Ben Slinger
Ben Slinger

πŸ’» ⚠️
Justin Dorfman
Justin Dorfman

πŸ”

This project follows the all-contributors specification. Contributions of any kind welcome!

LICENSE

MIT

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.