@ciscode/hooks-kit

12 production-ready React hooks. Zero runtime dependencies. SSR-safe.

Installation

npm install @ciscode/hooks-kit

React 18+ is required as a peer dependency:

npm install react react-dom

Usage

Import any hook directly from the package root — no deep imports needed:

import { useDebounce, useLocalStorage, useMediaQuery } from '@ciscode/hooks-kit';

SSR Compatibility

All DOM hooks (useMediaQuery, useWindowSize, useClickOutside, useIntersectionObserver) include typeof window === 'undefined' guards and are safe to render on the server (Next.js, Remix, etc.).

• useMediaQuery returns false on the server.
• useWindowSize returns { width: 0, height: 0 } on the server.
• useClickOutside and useIntersectionObserver skip effect registration on the server.
• All other hooks (useDebounce, useLocalStorage, useSessionStorage, usePrevious, useToggle, useInterval, useTimeout, useIsFirstRender) have no DOM dependency and work in any environment.

Hooks

State & Storage

useDebounce

Delays updating a value until a given delay has passed since the last change. Useful for search inputs and API calls.

Signature:

function useDebounce<T>(value: T, delay: number): T;

| Param | Type | Description | | ------- | -------- | ------------------------------------ | | value | T | The value to debounce | | delay | number | Milliseconds to wait before updating |

Returns: T — the debounced value.

Example:

import { useDebounce } from '@ciscode/hooks-kit';

function SearchInput() {
  const [query, setQuery] = useState('');
  const debouncedQuery = useDebounce(query, 300);

  useEffect(() => {
    if (debouncedQuery) fetchResults(debouncedQuery);
  }, [debouncedQuery]);

  return <input value={query} onChange={(e) => setQuery(e.target.value)} />;
}

useLocalStorage

Persists state in localStorage with JSON serialisation. Returns the initial value if the key is missing or the stored value is unparseable.

Signature:

function useLocalStorage<T>(key: string, initialValue: T): [T, Dispatch<SetStateAction<T>>];

| Param | Type | Description | | -------------- | -------- | ---------------------------------------------- | | key | string | The localStorage key | | initialValue | T | Fallback value when key is absent or corrupted |

Returns: [T, Dispatch<SetStateAction<T>>] — same tuple as useState.

Example:

import { useLocalStorage } from '@ciscode/hooks-kit';

function ThemeToggle() {
  const [theme, setTheme] = useLocalStorage<'light' | 'dark'>('theme', 'light');

  return (
    <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
      Current theme: {theme}
    </button>
  );
}

useSessionStorage

Same as useLocalStorage but backed by sessionStorage. Data is cleared when the browser tab closes.

Signature:

function useSessionStorage<T>(key: string, initialValue: T): [T, Dispatch<SetStateAction<T>>];

| Param | Type | Description | | -------------- | -------- | ---------------------------------------------- | | key | string | The sessionStorage key | | initialValue | T | Fallback value when key is absent or corrupted |

Returns: [T, Dispatch<SetStateAction<T>>] — same tuple as useState.

Example:

import { useSessionStorage } from '@ciscode/hooks-kit';

function Wizard() {
  const [step, setStep] = useSessionStorage('wizard-step', 1);

  return (
    <div>
      <p>Step {step}</p>
      <button onClick={() => setStep((s) => s + 1)}>Next</button>
    </div>
  );
}

DOM & Events

useMediaQuery

Reactively tracks a CSS media query. Uses useSyncExternalStore for concurrent-safe updates. Returns false on the server.

Signature:

function useMediaQuery(query: string): boolean;

| Param | Type | Description | | ------- | -------- | ------------------------------ | | query | string | A valid CSS media query string |

Returns: boolean — true when the query matches, false otherwise.

Example:

import { useMediaQuery } from '@ciscode/hooks-kit';

function Layout() {
  const isMobile = useMediaQuery('(max-width: 768px)');

  return <div>{isMobile ? <MobileNav /> : <DesktopNav />}</div>;
}

useWindowSize

Returns the current window dimensions, updated on resize with a 100 ms debounce. Returns { width: 0, height: 0 } on the server.

Signature:

function useWindowSize(): WindowSize;

interface WindowSize {
  width: number;
  height: number;
}

Returns: WindowSize — { width, height } in pixels.

Example:

import { useWindowSize } from '@ciscode/hooks-kit';

function Banner() {
  const { width } = useWindowSize();

  return <div>{width > 1024 ? 'Large screen' : 'Small screen'}</div>;
}

useClickOutside

Fires a callback whenever a mousedown or touchstart event occurs outside the referenced element. Safe to use with portals.

Signature:

function useClickOutside<T extends Element>(
  ref: RefObject<T | null>,
  handler: (event: MouseEvent | TouchEvent) => void,
): void;

| Param | Type | Description | | --------- | ------------------------------------------- | ------------------------------------ | | ref | RefObject<T \| null> | Ref attached to the element to watch | | handler | (event: MouseEvent \| TouchEvent) => void | Called when a click outside occurs |

Returns: void.

Example:

import { useRef } from 'react';
import { useClickOutside } from '@ciscode/hooks-kit';

function Dropdown({ onClose }: { onClose: () => void }) {
  const ref = useRef<HTMLDivElement>(null);
  useClickOutside(ref, onClose);

  return <div ref={ref}>Dropdown content</div>;
}

useIntersectionObserver

Observes when an element enters or exits the viewport using IntersectionObserver. Disconnects automatically on unmount.

Signature:

function useIntersectionObserver(
  ref: RefObject<Element | null>,
  options?: IntersectionObserverInit,
): IntersectionObserverEntry | null;

| Param | Type | Description | | --------- | ---------------------------- | -------------------------------------- | | ref | RefObject<Element \| null> | Ref attached to the element to observe | | options | IntersectionObserverInit | Optional threshold, root, rootMargin |

Returns: IntersectionObserverEntry | null — null until the first intersection event.

Example:

import { useRef } from 'react';
import { useIntersectionObserver } from '@ciscode/hooks-kit';

function LazyImage({ src }: { src: string }) {
  const ref = useRef<HTMLDivElement>(null);
  const entry = useIntersectionObserver(ref, { threshold: 0.1 });

  return (
    <div ref={ref}>{entry?.isIntersecting ? <img src={src} alt="" /> : <div>Loading…</div>}</div>
  );
}

Async & Lifecycle

usePrevious

Returns the value from the previous render. Returns undefined on the first render.

Signature:

function usePrevious<T>(value: T): T | undefined;

| Param | Type | Description | | ------- | ---- | ------------------ | | value | T | The value to track |

Returns: T | undefined — the previous value, or undefined on the first render.

Example:

import { usePrevious } from '@ciscode/hooks-kit';

function Counter() {
  const [count, setCount] = useState(0);
  const prevCount = usePrevious(count);

  return (
    <div>
      <p>
        Now: {count} — Before: {prevCount ?? 'none'}
      </p>
      <button onClick={() => setCount((c) => c + 1)}>Increment</button>
    </div>
  );
}

useToggle

Manages a boolean state with a stable toggle function. The toggle callback reference never changes between renders.

Signature:

function useToggle(initial?: boolean): [boolean, () => void];

| Param | Type | Description | | --------- | --------- | -------------------------------- | | initial | boolean | Initial state (default: false) |

Returns: [boolean, () => void] — current state and a stable toggle function.

Example:

import { useToggle } from '@ciscode/hooks-kit';

function Modal() {
  const [isOpen, toggle] = useToggle(false);

  return (
    <>
      <button onClick={toggle}>Open</button>
      {isOpen && (
        <dialog open>
          Content <button onClick={toggle}>Close</button>
        </dialog>
      )}
    </>
  );
}

useInterval

Runs a callback repeatedly at the given interval. Pass null as the delay to pause. The callback reference is always kept up to date — no stale closures.

Signature:

function useInterval(callback: () => void, delay: number | null): void;

| Param | Type | Description | | ---------- | ---------------- | ------------------------------------ | | callback | () => void | Function to call on each tick | | delay | number \| null | Interval in ms; pass null to pause |

Returns: void.

Example:

import { useState } from 'react';
import { useInterval } from '@ciscode/hooks-kit';

function Clock() {
  const [seconds, setSeconds] = useState(0);
  const [running, setRunning] = useState(true);

  useInterval(() => setSeconds((s) => s + 1), running ? 1000 : null);

  return (
    <div>
      <p>{seconds}s</p>
      <button onClick={() => setRunning((r) => !r)}>{running ? 'Pause' : 'Resume'}</button>
    </div>
  );
}

useTimeout

Runs a callback once after the given delay. Pass null to cancel. Cleans up automatically on unmount.

Signature:

function useTimeout(callback: () => void, delay: number | null): void;

| Param | Type | Description | | ---------- | ---------------- | ---------------------------------- | | callback | () => void | Function to call after the delay | | delay | number \| null | Delay in ms; pass null to cancel |

Returns: void.

Example:

import { useState } from 'react';
import { useTimeout } from '@ciscode/hooks-kit';

function Toast({ message }: { message: string }) {
  const [visible, setVisible] = useState(true);

  useTimeout(() => setVisible(false), 3000);

  return visible ? <div className="toast">{message}</div> : null;
}

useIsFirstRender

Returns true on the first render and false on every subsequent render. Useful for skipping effects on mount.

Signature:

function useIsFirstRender(): boolean;

Returns: boolean — true only on the first render.

Example:

import { useEffect } from 'react';
import { useIsFirstRender } from '@ciscode/hooks-kit';

function DataSync({ value }: { value: string }) {
  const isFirst = useIsFirstRender();

  useEffect(() => {
    if (isFirst) return; // skip on mount
    syncToServer(value);
  }, [value, isFirst]);

  return null;
}

Scripts

npm run build       # Build to dist/ (ESM + CJS + types)
npm test            # Run tests (vitest)
npm run typecheck   # TypeScript typecheck
npm run verify      # Lint + typecheck + tests + coverage

License

MIT — see LICENSE.

• npm run lint – ESLint
• npm run format / npm run format:write – Prettier
• npx changeset – create a changeset

Release flow (summary)

• Work on a feature branch from develop
• Merge to develop
• Add a changeset for user-facing changes: npx changeset
• Promote develop → master
• Tag vX.Y.Z to publish (npm OIDC)

This repository is a template. Teams should clone it and focus only on library logic, not tooling or release mechanics.