useToggle for React

Returns a boolean, a stable toggle and a setter for on or off state. For React, when you don't need useBoolean's named setTrue and setFalse helpers.

useToggle returns the boolean, a toggle, and the setter from useState. The toggle flips the current value and ignores extra click arguments.

Pass true to start on. Anything that is not a boolean throws during render. When you want setTrue and setFalse by name, use useBoolean. In React the toggle function stays the same between renders.

PreviewCode

Installation

Free with an account. It carries your token, so the CLI installs everything in one go.

Google GitHub

Use email insteadNo credit card

Anatomy

Usage

import { useToggle } from "@/hooks/use-toggle";

const [value, toggle, setValue] = useToggle();

Pass true to start on. toggle flips the boolean. setValue is the useState setter when you already know the next value.

FAQ

When should I use useToggle instead of useBoolean?

Use useToggle when you want a tuple of the boolean, a toggle, and a setter. Use useBoolean when the call site reads better with setTrue and setFalse named on the object. Both throw if the default is not a boolean, and both keep the toggle stable with an empty dependency list. The difference is the shape you pass into buttons, not a different idea of on and off.

Is the toggle function stable across renders?

Yes. It is wrapped in useCallback with an empty dependency list, and it only calls the state setter with a function, so it never needs the current boolean. The same function identity is safe in an effect dependency list, in a memoized child, and on a button click prop. The setter in the third position is also the stable setter from useState. Only the boolean in the first position changes when you toggle.

Can I set a specific value instead of toggling?

Yes. The third item is the setter from useState. Call it with true or false, or with a function that receives the previous boolean and returns the next one. Extra arguments are ignored by that setter, same as any useState setter. Toggle always flips. It does not look at an event you might pass from a click or a change handler, so it is safe to pass straight to onClick.

What happens if I pass a non-boolean default?

The hook throws before it calls useState. The error message says the default must be true or false. That runs during render, on the server and in the browser, so a bad default fails the render instead of storing a string or a number and then flipping it with a boolean not. TypeScript already rejects a non-boolean argument. The throw is there for plain JavaScript, where the parameter type is not checked.

How do I keep the toggle after a reload?

This hook does not read or write storage. Keep the boolean somewhere that persists, then pass that boolean as the default only for the first mount. A default is not a controlled value. Later changes to a prop will not update the state. If you need the stored value to win after mount, write a small effect that calls the setter when the stored value changes, or store the boolean in a hook that already talks to localStorage.

What is the default when I omit the argument?

The parameter defaults to false, so the first state is off. Pass true to start on. There is no controlled mode and no onChange callback. After mount, only toggle and the setter change the boolean. Rendering the hook again with a different argument does nothing, because useState keeps the first value. Unmounting and mounting again is what reads the argument a second time.