README.md

---

useSwitch()

npm i @react-hook/switch

---

A React hook for controlling a boolean value with toggle, on, and off callbacks. This is extremely useful for adding controlled/uncontrolled component behavior to components like <Checkbox/>, <Toggle/>, <Modal/>, etc.

Quick Start

import useSwitch from '@react-hook/switch'

// Basic usage
const Component = (props) => {
  const [value, toggle] = useSwitch(false /*default value*/)

  return (
    <>
      <span>Value: {value}</span>
      {/* toggles the current value to its opposite*/}
      <button onClick={toggle}>Toggle</button>
      {/* toggles the current value to true*/}
      <button onClick={toggle.on}>On</button>
      {/* toggles the current value to false*/}
      <button onClick={toggle.off}>Off</button>
    </>
  )
}

// Creating a toggle component with a controlled and uncontrolled
// value pattern
const Toggle = ({value: controlledValue, defaultValue, onChange}) => {
  const [value, toggle] = useSwitch(defaultValue, controlledValue, onChange)

  return (
    <>
      <span>Value: {value}</span>
      <button onClick={toggle}>Toggle</button>
      <button onClick={toggle.on}>On</button>
      <button onClick={toggle.off}>Off</button>
    </>
  )
}

API

useSwitch(defaultValue?, controlledValue?, onChange?)

function useSwitch(defaultValue?: boolean, controlledValue?: boolean, onChange?: (value: boolean, prevValue: boolean) => any): readonly [boolean, (() => void) & {
    on: () => void;
    off: () => void;
}]

Arguments

Argument	Type	Default	Required?	Description
defaultValue	boolean	false	No	Sets the default value of the switch
controlledValue	boolean	undefined	No	Sets the controlled value of the switch, which will override the defaultValue
onChange	(value: boolean) => any	undefined	No	A callback invoked whenever toggle callbacks that change state are invoked

Returns [value: boolean, toggle: Toggle]

Variable	Type	Description
value	boolean	Defines the initial value
toggle	() => void & {on: () => void, off: () => void}	If the value is true, calling this will make it false and vice-versa

() => void & {on: () => void, off: () => void}

Method	Type	Description
on	() => void	Switches the value to true
off	() => void	Switches the value to false

LICENSE

MIT