structyl/ Hooks

@structyl/hooks

Hooks

17 reusable, SSR-safe, tree-shakeable React hooks. Zero dependencies. Import only what you use.

useBoolean

State

Boolean state with named semantic setters.

(initial?: boolean) => { value, on, off, toggle, set }
OFF

Parameters

initialStarting value. Defaults to false.
Returns { value: boolean, on: () => void, off: () => void, toggle: () => void, set: Dispatch }

useToggle

State

Boolean state with a single toggle function.

(initial?: boolean) => [boolean, toggle, setValue]

value: false

Parameters

initialStarting value. Defaults to false.
Returns [value: boolean, toggle: () => void, setValue: (v: boolean) => void]

useCounter

State

Numeric counter with increment, decrement, and reset.

(initial?: number) => { count, increment, decrement, reset, set }
0

Parameters

initialStarting count. Defaults to 0.
Returns { count: number, increment: (by?: number) => void, decrement: (by?: number) => void, reset: () => void, set: Dispatch }

usePrevious

State

Returns the value from the previous render cycle.

<T>(value: T) => T | undefined

Previous

—

Current

0

Parameters

valueThe value to track.
Returns T | undefined — undefined on the first render.

useDebounce

Performance

Delays updating a value until after a quiet period. Ideal for search inputs.

<T>(value: T, delay?: number) => T
raw:empty
debounced (500ms):empty

Parameters

valueThe rapidly changing value to debounce.
delayMilliseconds to wait. Defaults to 300.
Returns T — the debounced value.

useThrottle

Performance

Limits how often a value updates to at most once per interval.

<T>(value: T, delay?: number) => T
raw:50
throttled (400ms):50

Parameters

valueThe rapidly changing value to throttle.
delayMinimum ms between updates. Defaults to 300.
Returns T — the throttled value.

useLocalStorage

Browser

State that persists in localStorage and syncs across tabs.

<T>(key: string, initial: T) => [T, setValue, remove]
localStorage["hooks-demo-name"]: empty

Refresh the page — the value stays.

Parameters

keyThe localStorage key.
initialFallback value when the key is absent.
Returns [value: T, setValue: (v: T | ((prev: T) => T)) => void, remove: () => void]

useCopyToClipboard

Browser

Copies text to the clipboard with a timed copied state.

() => { copy, copied, reset }
import { useCopyToClipboard } from '@structyl/hooks';
Returns { copy: (text: string) => Promise<boolean>, copied: boolean, reset: () => void }

useMediaQuery

Browser

Tracks any CSS media query. SSR-safe with a default value.

(query: string, defaultValue?: boolean) => boolean
sm (≥640px)false
md (≥768px)false
lg (≥1024px)false
reduced-motionfalse

Parameters

queryA valid CSS media query string.
defaultValueReturned during SSR. Defaults to false.
Returns boolean — whether the query currently matches.

useDarkMode

Browser

Returns true when the user prefers a dark color scheme.

() => boolean
☀️

System preference: light

Change your OS color scheme to see this update.

Returns boolean — true when prefers-color-scheme: dark.

useWindowSize

Browser

Tracks the browser viewport dimensions. SSR-safe.

() => { width: number, height: number }

Width

0

px

Height

0

px

Resize the window to see values update live.

Returns { width: number, height: number }

useClickOutside

DOM

Fires a handler when a pointer event lands outside the referenced element.

<T extends HTMLElement>(ref, handler, enabled?) => void

Parameters

refRef attached to the element to watch.
handlerCallback fired on outside click.
enabledWhether to listen. Defaults to true.
Returns void

useHotkeys

Keyboard

Binds keyboard shortcut combinations. Supports Ctrl, Meta, Shift, Alt, and Mod (cross-platform).

(keys: string, handler, options?) => void
Shift + ACtrl + KMod + Shift + P

Press one of the combos above…

Parameters

keysCombo string, e.g. "mod+k" or "ctrl+shift+s".
handlerCalled when the combo matches.
options.enableOnFormTagsAllow firing inside inputs. Defaults to false.
options.preventDefaultPrevent default browser action. Defaults to true.
Returns void

useMount

Lifecycle

Runs a callback exactly once when the component mounts.

(callback: () => void) => void

Parameters

callbackFunction to run on mount.
Returns void

useUnmount

Lifecycle

Runs a callback when the component unmounts. Uses a stable ref to avoid stale closures.

(callback: () => void) => void

Parameters

callbackCleanup function to run on unmount.
Returns void

useUpdateEffect

Lifecycle

Identical to useEffect but skips the initial run on mount — only fires on subsequent renders.

(effect: EffectCallback, deps?: DependencyList) => void
Updates (mount skipped)0

Parameters

effectEffect to run on updates.
depsDependency array, same as useEffect.
Returns void

useId

Utility

Generates a stable unique ID. SSR-safe wrapper around React.useId with optional prefix.

(prefix?: string) => string
useId("input")input-_R_e6aav5tdb_
useId("label")label-_R_e6aav5tdbH1_
useId()_R_e6aav5tdbH2_

Stable across re-renders. SSR-safe.

Parameters

prefixOptional string prepended to the ID.
Returns string — a stable, unique ID.