Join our Discord Community
shadcn.io

useToggle

React hook for toggle state management with array return pattern similar to useState. Perfect for React applications requiring clean boolean toggling with Next.js integration and TypeScript support.

Loading component...

Installation

npx shadcn@latest add https://www.shadcn.io/registry/use-toggle.json
npx shadcn@latest add https://www.shadcn.io/registry/use-toggle.json
pnpm dlx shadcn@latest add https://www.shadcn.io/registry/use-toggle.json
bunx shadcn@latest add https://www.shadcn.io/registry/use-toggle.json

Features

  • Array return pattern following useState convention with value, toggle, and setValue
  • Memoized toggle function using useCallback for optimal performance
  • Direct state access with setValue for custom logic and conditional updates
  • Type safety with comprehensive TypeScript definitions and error handling
  • Default value support with boolean validation and descriptive error messages
  • Memory efficient with proper callback memoization to prevent unnecessary re-renders

Examples

Advanced Multi-Toggle Interface

Loading component...

Demonstrates multiple toggle states working together with action history and theme switching.

Use Cases

This free open source React hook works well for:

  • Feature flags - Enable/disable features with clean toggle interface built with Next.js
  • UI state management - Show/hide components, expand/collapse panels using TypeScript
  • Theme switching - Dark mode, layout preferences with array destructuring pattern
  • Form controls - Checkboxes, switches, and boolean form fields
  • Visibility toggles - Modal states, dropdown menus, and sidebar controls
  • Settings panels - User preferences and configuration toggles

API Reference

useToggle

ParameterTypeDefaultDescription
defaultValuebooleanfalseInitial toggle state. Must be a valid boolean or throws error

Return Array

IndexTypeDescription
[0]booleanCurrent toggle state value
[1]() => voidMemoized function to toggle the current state
[2]React.Dispatch<React.SetStateAction<boolean>>Direct state setter (same as useState)

Usage Patterns

Basic Array Destructuring

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

// Toggle the state
toggle();

// Set specific value
setValue(true);
setValue(false);

// Custom toggle logic
setValue((prev) => !prev);

With Initial Value

const [isExpanded, toggleExpanded, setExpanded] = useToggle(true);

Feature Flag Pattern

const [isFeatureEnabled, toggleFeature, setFeatureEnabled] = useToggle();

const enableFeature = () => setFeatureEnabled(true);
const disableFeature = () => setFeatureEnabled(false);

return (
  <>
    {isFeatureEnabled && <NewFeature />}
    <button onClick={toggleFeature}>Toggle Feature</button>
  </>
);

Theme Management

const [isDark, toggleTheme, setTheme] = useToggle(false);

const switchToLight = () => setTheme(false);
const switchToDark = () => setTheme(true);

return (
  <div className={isDark ? "dark-theme" : "light-theme"}>
    <button onClick={toggleTheme}>Switch Theme</button>
  </div>
);

Comparison with useBoolean

FeatureuseToggleuseBoolean
Return PatternArray [value, toggle, setValue]Object {value, setValue, setTrue, setFalse, toggle}
useState-like✅ Similar to useState❌ Object destructuring
Helper Methods❌ Only toggle function✅ setTrue, setFalse methods
Rename on Destructure✅ Easy to rename❌ Must use aliases
TypeScript Inference✅ Excellent with arrays✅ Good with objects

Implementation Notes

  • Hook validates that defaultValue is a boolean and throws descriptive error if not
  • Toggle function is memoized with useCallback for performance optimization
  • setValue works exactly like useState setter with function and value support
  • Array return pattern allows easy renaming during destructuring
  • Compatible with React 16.8+ and follows all hooks rules and conventions
  • Works seamlessly with TypeScript for full type safety and IntelliSense
  • Memory efficient with stable function references across re-renders

useTimeout

React hook for declarative setTimeout management with automatic cleanup and dynamic delay control. Perfect for React applications requiring timed actions with Next.js integration and TypeScript support.

useUnmount

React hook for running cleanup logic when a component unmounts. Perfect for React applications requiring cleanup tasks like canceling subscriptions with Next.js integration and TypeScript support.