@structyl/hooks

A collection of SSR-safe, tree-shakeable React hooks for state, refs, the DOM, browser APIs, and performance.

npm license

@structyl/hooks is the shared hook layer of structyl, the React UI library with structure. It packages the small, single-responsibility hooks that the primitives and styled components rely on, such as useControllableState for controlled/uncontrolled state and useComposedRefs for merging refs. Every hook is SSR-safe (no unguarded window/document access) and tree-shakeable, so it is equally useful on its own in any React 18 or 19 application.

Installation

# pnpm
pnpm add @structyl/hooks

# npm
npm install @structyl/hooks

# yarn
yarn add @structyl/hooks

React 18 or 19 (and react-dom) are peer dependencies.

Usage

import {
  useControllableState,
  useDebounce,
  useLocalStorage,
} from '@structyl/hooks';

function SearchField({ value, defaultValue = '', onChange }: {
  value?: string;
  defaultValue?: string;
  onChange?: (next: string) => void;
}) {
  // Works in both controlled and uncontrolled modes.
  const [query, setQuery] = useControllableState({
    prop: value,
    defaultProp: defaultValue,
    onChange,
  });

  // Only react to the value after the user stops typing.
  const debouncedQuery = useDebounce(query ?? '', 300);

  // Persist the last search across reloads (SSR-safe).
  const [recent, setRecent] = useLocalStorage<string[]>('recent-searches', []);

  return (
    <input
      type="search"
      value={query ?? ''}
      onChange={(event) => setQuery(event.target.value)}
      onBlur={() => debouncedQuery && setRecent([debouncedQuery, ...recent])}
      placeholder="Search…"
    />
  );
}

Features

Controllable state — useControllableState is the cornerstone hook for building components that work in both controlled and uncontrolled modes.
SSR-safe by default — browser-bound hooks guard window/document access and degrade gracefully on the server.
Tree-shakeable — named exports and sideEffects: false mean you only ship the hooks you import.
Ref composition — useComposedRefs / composeRefs merge multiple refs onto a single node, the foundation of asChild patterns.
TypeScript-first — fully typed signatures with generics and tuple returns; no any.
ESM + CJS — ships both module formats plus type declarations.

API

State

Hook	Description
`useControllableState`	Manage state that may be controlled by a parent or held internally.
`useToggle`	Boolean state with a toggle and explicit setter `[value, toggle, set]`.
`useBoolean`	Boolean state with `{ value, on, off, toggle, set }` helpers.
`useCounter`	Numeric state with `increment`, `decrement`, `reset`, and `set`.
`usePrevious`	Returns the value from the previous render.

Refs

Hook	Description
`useComposedRefs` / `composeRefs`	Merge multiple refs (callback or object) onto one node.
`useCallbackRef`	Stabilize a callback as a ref to avoid re-renders.
`useLatest`	Keep a ref pointing at the latest value without re-rendering.

DOM

Hook	Description
`useClickOutside`	Run a handler when a click/touch lands outside a ref.
`useEventListener`	Typed `addEventListener` for `window`, `document`, or an element.
`useKeyPress`	Run a handler when a specific key is pressed.

Browser

Hook	Description
`useMediaQuery`	Subscribe to a CSS media query, with an SSR default.
`useLocalStorage`	JSON-backed `localStorage` state `[value, set, remove]`, synced across tabs.
`useCopyToClipboard`	Copy text and track `copied` state via the Clipboard API.
`useDarkMode`	Boolean for the `prefers-color-scheme: dark` query.

Performance

Hook	Description
`useDebounce`	Debounce a value by a delay (default `300ms`).
`useThrottle`	Throttle a value by a delay (default `300ms`).

Utility

Hook	Description
`useId`	SSR-safe stable ID wrapping `React.useId` with an optional prefix.
`useMount`	Run a callback once on mount.
`useUnmount`	Run a callback on unmount.
`useUpdateEffect`	Like `useEffect`, but skips the first run.
`useIsomorphicLayoutEffect`	`useLayoutEffect` on the client, `useEffect` on the server.
`useWindowSize`	Track `{ width, height }` of the window.
`useHotkeys`	Bind keyboard shortcuts (e.g. `mod+k`) with modifier support.

Part of structyl

Part of structyl — see the full documentation at www.structyl.com.

License

MIT