@usefy/use-toggle
v0.2.6TypeScript
A React hook for boolean state management
91/weekUpdated 1 weeks agoMITUnpacked: 20.1 KB
Published by mirunamu
npm install @usefy/use-toggle
@usefy/use-toggle
A lightweight, type-safe React hook for boolean state management
Installation •
Quick Start •
API Reference •
Examples •
License
---
Overview
@usefy/use-toggle is a powerful React hook for managing boolean state with helpful utilities. It provides toggle, setTrue, setFalse, and setValue functions, making it perfect for modals, dropdowns, accordions, and any UI component with on/off states.
Part of the @usefy ecosystem — a collection of production-ready React hooks designed for modern applications.
$3
- Zero Dependencies — Pure React implementation with no external dependencies
- TypeScript First — Full type safety with exported interfaces
- Stable References — All functions are memoized with useCallback for optimal performance
- SSR Compatible — Works seamlessly with Next.js, Remix, and other SSR frameworks
- Lightweight — Minimal bundle footprint (~300B minified + gzipped)
- Well Tested — Comprehensive test coverage with Vitest
---
Installation
``bashnpm
npm install @usefy/use-toggle
yarn
yarn add @usefy/use-toggle
pnpm
pnpm add @usefy/use-toggle
`
$3
This package requires React 18 or 19:
json
{
"peerDependencies": {
"react": "^18.0.0 || ^19.0.0"
}
}
`---
Quick Start
tsx
import { useToggle } from "@usefy/use-toggle";function Modal() {
const { value: isOpen, toggle, setTrue, setFalse } = useToggle(false);
return (
<>
{isOpen && (
Modal Content
)}
);
}
`---
API Reference
$3
A hook that manages boolean state with toggle, setTrue, setFalse, and setValue functions.
#### Parameters
| Parameter | Type | Default | Description |
| -------------- | --------- | ------- | ------------------------- |
|
| boolean | false | The initial boolean value |#### Returns
UseToggleReturn| Property | Type | Description |
| ---------- | -------------------------- | ------------------------------------ |
|
| boolean | The current boolean state |
| toggle | () => void | Toggles the value (true ↔ false) |
| setTrue | () => void | Sets the value to true |
| setFalse | () => void | Sets the value to false |
| setValue | (value: boolean) => void | Sets the value to a specific boolean |---
Examples
$3
`tsx
import { useToggle } from "@usefy/use-toggle";function ConfirmDialog() {
const { value: isOpen, setTrue: open, setFalse: close } = useToggle(false);
return (
<>
{isOpen && (
Confirm Deletion
Are you sure you want to delete this item?
deleteItem();
close();
}}
>
Delete
)}
);
}
`$3
tsx
import { useToggle } from "@usefy/use-toggle";function AccordionItem({ title, content }: AccordionItemProps) {
const { value: isExpanded, toggle } = useToggle(false);
return (
onClick={toggle}
aria-expanded={isExpanded}
>
{title}
icon ${isExpanded ? "rotate" : ""}}>▼
{isExpanded && {content}}
);
}
`$3
tsx
import { useToggle } from "@usefy/use-toggle";function ThemeToggle() {
const { value: isDark, toggle, setValue } = useToggle(false);
// Sync with system preference
useEffect(() => {
const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
setValue(mediaQuery.matches);
}, [setValue]);
return (
aria-label={
Switch to ${isDark ? "light" : "dark"} mode}
>
{isDark ? "🌙" : "☀️"}
);
}
`$3
tsx
import { useToggle } from "@usefy/use-toggle";function Dropdown({ items }: DropdownProps) {
const { value: isOpen, toggle, setFalse: close } = useToggle(false);
return (
{isOpen && (
{items.map((item) => (
item.onClick();
close();
}}
>
{item.label}
))}
)}
);
}
`$3
tsx
import { useToggle } from "@usefy/use-toggle";function ControlledSwitch({ defaultChecked, onChange }: SwitchProps) {
const { value, toggle } = useToggle(defaultChecked);
const handleToggle = () => {
toggle();
onChange?.(!value);
};
return (
aria-checked={value}
onClick={handleToggle}
className={
switch ${value ? "on" : "off"}}
>
);
}
`---
TypeScript
This hook is written in TypeScript and exports the
interface.`tsx
import { useToggle, type UseToggleReturn } from "@usefy/use-toggle";// Return type is fully typed
const { value, toggle, setTrue, setFalse, setValue }: UseToggleReturn =
useToggle(false);
// value: boolean
// toggle: () => void
// setTrue: () => void
// setFalse: () => void
// setValue: (value: boolean) => void
`---
Performance
All functions returned by the hook are memoized using
, ensuring stable references across re-renders. This makes them safe to use as dependencies in other hooks or as props to child components.`tsx
const { toggle, setTrue, setFalse, setValue } = useToggle(false);// These references remain stable across renders
useEffect(() => {
// Safe to use as dependencies
}, [toggle, setTrue, setFalse, setValue]);
``---
Testing
This package maintains comprehensive test coverage to ensure reliability and stability.
$3
📊 View Detailed Coverage Report (GitHub Pages)
$3
Initialization Tests
- Default value initialization (false)
- Custom initial value (true/false)
- Return all required functions
Toggle Tests
- Toggle from false to true
- Toggle from true to false
- Multiple toggles
- Rapid successive toggles
setTrue/setFalse Tests
- Set value from opposite state
- Maintain value when already set
- Multiple consecutive calls
- After toggle operations
Function Reference Tests
- Stable toggle reference across renders
- Stable setTrue reference across renders
- Stable setFalse reference across renders
- Stable setValue reference across renders
- All references stable after multiple operations
---
License
MIT © mirunamu
This package is part of the usefy monorepo.
---
Built with care by the usefy team