Nutritious Pomegranate Muffins
    Wondering what’s next for npm?Check out our public roadmap! »

    react-toggled
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.7 • Public • Published

    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(
      <Toggle>
        {({on, getTogglerProps}) => (
          <div>
            <button {...getTogglerProps()}>Toggle me</button>
            <div>{on ? 'Toggled On' : 'Toggled Off'}</div>
          </div>
        )}
      </Toggle>,
      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 <Toggle>{/* your function here! */}</Toggle>.

    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 <input />). 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: <Toggle>{/* right here*/}</Toggle>

    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

    💻 📖 🚇 ⚠️

    Frank Tan

    💻 📖 ⚠️

    Oliver

    💻

    Jedrzej Lewandowski

    💻

    Ben Slinger

    💻 ⚠️

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

    LICENSE

    MIT

    Install

    npm i react-toggled

    DownloadsWeekly Downloads

    26,265

    Version

    1.2.7

    License

    MIT

    Unpacked Size

    81.1 kB

    Total Files

    18

    Last publish

    Collaborators

    • avatar