useToggle

Category

Utilities

Export Size

702 B

Last Changed

5 days ago

A boolean (or value) toggler with controllable state support.

Demo

Usage

import { useToggle } from '@reause/shared'
import { useState } from 'react'

const [value, toggle] = useToggle()

// A State<T> input can be controlled with a React state tuple.
const controlled = useState(false)
const [controlledValue, controlledToggle] = useToggle(controlled)

toggle() // false → true
toggle() // true → false
toggle(false) // force to false
toggle(c => !c) // functional update

Toggle Function

The toggle function can be called in two ways:

const [value, toggle] = useToggle()

toggle() // toggle between true and false
toggle(true) // set to specific value

Unlike upstream, the toggle function does not return the new value — React state updates are asynchronous, so read it from value on the next render.

Custom Values

You can use custom truthy and falsy values instead of true and false:

import { useToggle } from '@reause/shared'

const [value, toggle] = useToggle('on', {
  truthyValue: 'on',
  falsyValue: 'off',
})

toggle() // 'off'
toggle() // 'on'

Upstream allows the custom values to be reactive refs; this port accepts plain values only.

Type Declarations

export interface UseToggleOptions<Truthy, Falsy> {
    truthyValue?: Truthy;
    falsyValue?: Falsy;
}

export type UseToggleReturn<T extends boolean | number | string = boolean> = [
    T,
    (value?: T | ((current: T) => T)) => void
]

export type State<T> = StateValue<T>

export function useToggle<T extends boolean | number | string = boolean, Truthy = true, Falsy = false>(initialValue?: State<T>, options?: UseToggleOptions<Truthy, Falsy>): UseToggleReturn<T>

export function useControllableState<T>(state: State<T>, options?: UseControllableStateOptions<T>): StateTuple<T>

Source

Source · Demo

Contributors

Changelog

v0.1.0 on

ac5e2 - fix(shared): resolve useToggle audit findings (#751)