/@structyl/hooks
24 reusable, SSR-safe, tree-shakeable React hooks. Zero dependencies. Import only what you use.
pnpm add @structyl/hooksBoolean state with named semantic setters: on, off, toggle.
(initial?: boolean) => { value, on, off, toggle, set }Parameters
initialStarting value. Defaults to false.{ value: boolean, on, off, toggle, set }Boolean state with a single toggle function and optional value setter.
(initial?: boolean) => [boolean, toggle, setValue]value: falseParameters
initialStarting value. Defaults to false.[value: boolean, toggle: () => void, setValue: Dispatch<boolean>]Numeric counter with increment, decrement, reset, and custom step support.
(initial?: number) => { count, increment, decrement, reset, set }Parameters
initialStarting count. Defaults to 0.{ count: number, increment(by?), decrement(by?), reset, set }Captures the value from the previous render. Useful for comparing changes.
<T>(value: T) => T | undefinedPrevious
—
Current
0
Parameters
valueThe value to track across renders.T | undefined — undefined on the first render.Delays updating a value until after a quiet period. Ideal for search inputs and API calls.
<T>(value: T, delay?: number) => TParameters
valueThe rapidly changing value.delayQuiet period in ms. Defaults to 300.T — the debounced value.Limits how often a value updates to at most once per interval.
<T>(value: T, delay?: number) => TParameters
valueThe rapidly changing value.delayMinimum ms between updates. Defaults to 300.T — the throttled value.State that persists in localStorage and syncs across browser tabs automatically.
<T>(key: string, initial: T) => [T, setValue, remove]"structyl-hooks-demo": nullParameters
keyThe localStorage key.initialFallback when key is absent.[value: T, setValue, remove: () => void]Copies text to the clipboard. Returns a timed copied state that auto-resets after 2s.
() => { copy, copied, reset }import { useCopyToClipboard } from '@structyl/hooks';{ copy: (text) => Promise<boolean>, copied: boolean, reset: () => void }Tracks any CSS media query and returns a boolean. SSR-safe with a configurable default.
(query: string, defaultValue?: boolean) => booleansm ≥640pxfalsemd ≥768pxfalselg ≥1024pxfalsereduced-motionfalseParameters
queryA valid CSS media query.defaultValueValue returned during SSR. Defaults to false.booleanReturns true when the system prefers a dark color scheme.
() => booleanisDark: falseChange your OS color scheme to update
booleanTracks the live viewport dimensions. SSR-safe (defaults to 0 × 0).
() => { width: number, height: number }Width
0
px
Height
0
px
Resize the window to see it update
{ width: number, height: number }Fires a callback when a pointer event lands outside the referenced element. Listens to mousedown and touchstart.
<T extends HTMLElement>(ref, handler, enabled?) => voidParameters
refRef attached to the element to watch.handlerCalled on outside click.enabledWhether to listen. Defaults to true.voidBinds keyboard shortcut combinations. Supports mod (Ctrl on Windows, Cmd on Mac), shift, alt.
(keys: string, handler, options?) => voidPress a combo above…
Parameters
keysCombo string, e.g. "mod+k" or "ctrl+shift+s".handlerCalled when the combo fires.options.enableOnFormTagsAllow firing in inputs. Default false.options.preventDefaultPrevent default action. Default true.voidRuns a callback exactly once when the component mounts.
(callback: () => void) => voidParameters
callbackFunction to run on mount.voidRuns a callback on unmount. Uses a stable ref internally — safe to pass fresh closures.
(callback: () => void) => voidParameters
callbackCleanup function.voidLike useEffect but skips the initial mount — only runs on subsequent dependency changes.
(effect: EffectCallback, deps?: DependencyList) => voidParameters
effectEffect to run on updates.depsDependency array, same as useEffect.voidGenerates a stable unique ID. Thin SSR-safe wrapper around React.useId with optional prefix.
(prefix?: string) => stringuseId("input")input-_R_3hqnpfl5tdb_useId("label")label-_R_3hqnpfl5tdbH1_useId()_R_3hqnpfl5tdbH2_Stable across re-renders · SSR-safe
Parameters
prefixOptional string prepended to the ID.string — a stable unique ID.Bridges controlled and uncontrolled state. Lets a component accept an optional value prop without duplicating internal state logic.
<T>({ prop, defaultProp, onChange }) => [T | undefined, setter]value = "uncontrolled"Parameters
propExternal controlled value. Undefined means uncontrolled.defaultPropInitial value for uncontrolled mode.onChangeCalled whenever the value changes.[value: T | undefined, setValue]Merges multiple refs into a single callback ref. Essential when forwarding an external ref while keeping an internal one.
<T>(...refs: Ref<T>[]) => RefCallback<T>ref1 attached: falseref2 attached: falseSame node: true · clicks: 0Parameters
...refsAny mix of callback refs and object refs to merge.RefCallback<T> — assign to the ref prop of any element.Returns a stable function identity that always calls the latest version of the callback. Eliminates stale-closure bugs without adding the callback to effect deps.
<T extends Fn>(callback: T | undefined) => TIncrement then log — always sees the latest count
Parameters
callbackThe fresh callback to stabilize.T — a stable reference that never changes identity.A ref whose .current always holds the latest value. Use inside intervals, timeouts, or event handlers to avoid reading stale closures.
<T>(value: T) => { readonly current: T }Press "Read ref" to see the latest valueParameters
valueThe value to keep perpetually current.{ readonly current: T } — a ref that is always up to date.Declarative addEventListener with automatic cleanup. Attaches to window by default, or any element via the optional third argument.
(event, handler, element?) => voidPress any letter key on your keyboard
waiting…Parameters
eventDOM event name (e.g. "keydown", "scroll", "resize").handlerEvent handler. Stabilized internally.elementTarget. Defaults to window.voidFires a handler whenever a specific key is pressed. Thin wrapper around useEventListener — auto-cleans up on unmount.
(key: string, handler: (e: KeyboardEvent) => void) => voidPress ↑ or ↓ arrow keys
Parameters
keyKey value to watch (e.g. "Enter", "ArrowUp", "Escape").handlerCalled when the key is pressed.voidSSR-safe useLayoutEffect. Uses useLayoutEffect in the browser (runs synchronously before paint) and falls back to useEffect on the server — no hydration warnings.
(effect: EffectCallback, deps?: DependencyList) => void0 × 0px — read before first paintuseLayoutEffect on client · useEffect on server
Parameters
effectEffect to run. Synchronous before paint on the client.depsDependency array, same as useEffect.void