Billing overview

API signature

Set a document title and restore the previous title on cleanup. ```ts export declare function useDocumentTitle( // The document title while this hook owns it. The previous title is restored on cleanup. title: string ): // Returns: Nothing to store: the hook updates the browser tab title. Use one title owner at a time. void; ```

Staging preview. The tab icon uses your app’s /staging-icon.svg asset.

API signature

Set the favicon while mounted; restore or remove the owned link on cleanup. ```ts export declare function useFavicon( // The URL of the icon to apply while mounted; supply this asset in your app. href: string ): // Returns: Nothing to store: the icon is restored or removed on cleanup. Use one favicon owner at a time. void; ```

{open && ( )}

API signature

Reference-counted body scroll lock that handles overlapping dialogs. ```ts export declare function useLockBodyScroll( // Whether body scrolling should be locked. Defaults to true. locked?: boolean ): // Returns: Nothing to store: overlapping locks are counted so one closing surface does not unlock another. void; ```

(null); const [changes, setChanges] = useState(0); useMutationObserver( element, (records) => setChanges((value) => value + records.length), { childList: true, subtree: true, characterData: true }, ); return (

Observed mutations: {changes}

); } ```

API signature

Observe DOM mutations with stable callbacks and cleanup on target changes. ```ts export declare function useMutationObserver( // The DOM node to observe; null disables observation. target: Node | null, // The browser MutationObserver callback, receiving mutation records and the observer. callback: MutationCallback, // Which mutations to observe. Defaults to childList: true; choose the smallest useful scope. options?: MutationObserverInit ): // Returns: Nothing to store: the observer disconnects when the target/settings change or the component unmounts. void; ```

## useQueryParams **Filters that can travel in a link** An issue list keeps its status filter in the URL so a teammate can open the same view. **Why this hook helps:** The setter patches selected parameters while preserving unrelated query values and the fragment. **Keep in mind:** This example uses native history. Inject a router-aware adapter in Next.js or another framework so its navigation state remains consistent. [Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useQueryParams.tsx) ```tsx 'use client'; import { useQueryParams } from 'use-a-hook'; export default function ShareableIssueFilter() { const [params, setParams] = useQueryParams(); const status = params.get('status') ?? 'open'; return ( Issue status{' '} ); } ```

API signature

URL search state through an injected router adapter or native browser navigation. ```ts export interface QueryParamsAdapter { // Subscribe to URL changes, call notify after navigation, and return a cleanup function. subscribe: (notify: () => void) => () => void; // Return the current query string. Keep the same string while the URL has not changed. getSnapshot: () => string; // Optional query string for server rendering; defaults to an empty string. getServerSnapshot?: () => string; // Update the URL through your router. replace=true replaces the current history entry. navigate: (search: string, replace: boolean) => void; } export declare function useQueryParams( // Optional router integration. Omit for native browser history; framework apps should supply a router-aware adapter. adapter?: QueryParamsAdapter ): // Returns: A read view of search parameters and a setter that preserves unrelated parameters. readonly [ // The current URLSearchParams. Read it here; use the setter rather than mutating this object. URLSearchParams, // Patch selected keys with strings or string arrays; null removes a key. options.replace defaults to true. (patch: Record, options?: { replace?: boolean; }) => void ]; ```

## useHash **A bookmark for the right shelf** A settings preview uses the URL fragment to point to a section. **Why this hook helps:** The hook follows native hash changes and updates the fragment without dropping existing query parameters. **Keep in mind:** Native fragment navigation may scroll to a matching element. Prefer semantic anchor links when no JavaScript state is required. [Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useHash.tsx) ```tsx 'use client'; import { useHash } from 'use-a-hook'; export default function SettingsSections() { const [section, setSection] = useHash(); return (

Current section: {section || 'none selected'}

Profile

Billing

); } ```

API signature

Subscribe to URL fragment changes and set fragments without dropping the query. ```ts export declare function useHash(): // Returns: The URL fragment without its leading # and a setter using native fragment navigation. readonly [ // The current fragment text; empty when no fragment is present. string, // Set the fragment text. Native navigation may scroll to an element with that ID. (value: string) => void ]; ```

## useBroadcastChannel **Two tabs exchange sticky notes** A settings screen tells another open tab that shared data should be refreshed. **Why this hook helps:** BroadcastChannel delivers same-origin messages without building a server connection for local tab coordination. **Keep in mind:** Open the example in two tabs. A channel does not receive its own posts; messages are not durable and are not an authorization mechanism. [Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useBroadcastChannel.tsx) ```tsx 'use client'; import { useState } from 'react'; import { useBroadcastChannel } from 'use-a-hook'; export default function CrossTabRefresh() { const channel = useBroadcastChannel<{ type: 'refresh'; at: number }>( 'demo-workspace-events', ); const [status, setStatus] = useState(''); return (

{status}

{channel.message && (

Another tab requested a refresh at{' '} {new Date(channel.message.at).toISOString()}.

)}

); } ```

API signature

Cross-tab messages with a channel scoped to the mounted hook. ```ts export declare function useBroadcastChannel< // The expected message shape. Validate messages at your application boundary. T = unknown >( // The same-origin channel name. Changing it closes the old channel. name: string, // Optional function called with each incoming message; the latest committed function is used. onMessage?: (message: T) => void ): // Returns: The latest received message and a post action for other channel consumers. { // The latest incoming value, or undefined before a message arrives; own posts are not echoed. message: T | undefined; // Send a value that the browser can copy. Returns false when unavailable; copying errors can still throw. post: (value: T) => boolean; }; ```

## useAsyncTask **The latest preview wins the audition** A user requests an invoice preview, then changes their mind before the first response finishes. **Why this hook helps:** Starting another run aborts the earlier signal and prevents its stale completion from replacing the current result. **Keep in mind:** Implement the endpoint in your app and inspect task.status. Undefined can be a valid result as well as the result of cancellation or failure. [Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useAsyncTask.tsx) ```tsx 'use client'; import { useAsyncTask } from 'use-a-hook'; export default function InvoicePreviewLoader() { const preview = useAsyncTask(async (signal, invoiceId: string) => { const response = await fetch( `/api/invoices/${encodeURIComponent(invoiceId)}/preview`, { signal }, ); if (!response.ok) throw new Error('Could not load invoice preview.'); return response.text(); }); return (

{preview.pending &&

Loading…

} {preview.status === 'error' &&

Preview failed.

} {preview.data &&

{preview.data}

}

); } ```

API signature

Run cancellable user-triggered tasks with latest-result protection and explicit status. ```ts export interface AsyncTaskState { // idle before work, pending while running, success after completion, or error after failure. status: 'idle' | 'pending' | 'success' | 'error'; // The latest successful result; undefined before success or after a failed run. data: T | undefined; // The last failure value, or undefined when there is no failure. error: unknown; } export declare function useAsyncTask< // The list of argument types your run function accepts. A extends unknown[], // The successful result type returned by the async task. T >( // An async function receiving the hook-owned AbortSignal first, then your arguments. Pass the signal to cancellable work. task: (signal: AbortSignal, ...args: A) => Promise ): // Returns: The task status, result, and stable run/cancel/reset actions. { // True only while the current task is running. pending: boolean; // Start a task with its arguments; a newer run cancels the previous signal. Failures/cancellation resolve to undefined and update status. run: (...args: A) => Promise; // Cancel the current signal and clear its pending/error status; does not undo server work. cancel: () => void; // Cancel work and return to idle with no result or error. reset: () => void; // idle before work, pending while running, success after completion, or error after failure. status: "error" | "idle" | "pending" | "success"; // The latest successful result; undefined before success or after a failed run. data: T | undefined; // The last failure value, or undefined when there is no failure. error: unknown; }; ```

## usePolling **The export checker waits its turn** An export screen checks a background job until it is ready, without starting a second check while the first is pending. **Why this hook helps:** The next timeout is scheduled after completion. Optional polling pauses when the document is hidden by default. **Keep in mind:** Your app supplies /api/exports/demo/status. Disable polling when work is complete, and use a query library if it already owns this resource. [Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/usePolling.tsx) ```tsx 'use client'; import { useState } from 'react'; import { usePolling } from 'use-a-hook'; export default function ExportStatus() { const [enabled, setEnabled] = useState(false); const job = usePolling( async (signal) => { const response = await fetch('/api/exports/demo/status', { signal }); if (!response.ok) throw new Error('Status check failed.'); const result = (await response.json()) as { ready: boolean }; if (result.ready) setEnabled(false); return result; }, { interval: 3000, enabled }, ); return (

{job.data?.ready ? 'Export ready!' : 'Not ready yet.'}

{job.status === 'error' &&

Could not check the export.

}

); } ```

API signature

Non-overlapping polling that waits for completion and pauses in hidden documents by default. ```ts export interface PollingOptions { // Wait between completion and the next check, in milliseconds. interval: number; // Whether automatic polling is active. Defaults to true. enabled?: boolean; // Whether to check immediately on activation. Defaults to true. immediate?: boolean; // Whether to keep checking in hidden tabs. Defaults to false. background?: boolean; } export declare function usePolling< // The successful result type from each check. T >( // Async work receiving an AbortSignal. Automatic checks wait for completion before scheduling the next one. task: (signal: AbortSignal) => Promise, // Polling interval, enablement, first-run timing, and hidden-tab behavior. { interval, enabled, immediate, background }: PollingOptions ): // Returns: Async-task state and actions; use options.enabled to stop the automatic polling loop. { // True only while the current task is running. pending: boolean; // Manually start a check. Avoid this if the automatic loop should be the sole request owner. run: () => Promise; // Cancel the current check; this alone does not disable future automatic checks. cancel: () => void; // Cancel work and return to idle with no result or error. reset: () => void; // idle before work, pending while running, success after completion, or error after failure. status: "error" | "idle" | "pending" | "success"; // The latest successful result; undefined before success or after a failed run. data: T | undefined; // The last failure value, or undefined when there is no failure. error: unknown; }; ```

## useAutosave **The draft has a patient filing clerk** A notes editor saves after typing settles and keeps newer edits queued while a save is in progress. **Why this hook helps:** Debouncing reduces chatter, serialization preserves save order, and failures remain dirty for an explicit retry. **Keep in mind:** This self-contained example saves to localStorage. Replace the callback with your API and handle server versions/conflicts there; unmount does not flush automatically. [Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useAutosave.tsx) ```tsx 'use client'; import { useState } from 'react'; import { useAutosave } from 'use-a-hook'; export default function AutosavedNote() { const [note, setNote] = useState(''); const save = useAutosave( note, async (captured, signal) => { if (signal.aborted) throw new Error('Cancelled.'); localStorage.setItem('demo-autosaved-note', captured); }, { delay: 500 }, ); return (

setNote(event.target.value)}
      />
      <button onClick={() => void save.flush()}>Save now / retry</button>
      <p role="status">
        {save.saving
          ? 'Filing the note…'
          : save.dirty
            ? 'Edits waiting to be saved.'
            : 'No unsaved edits.'}
      </p>
      {Boolean(save.error) && (
        <p role="alert">Save failed. Your current edits are still here.</p>
      )}
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Debounced, serialized saves with queued edits, explicit flush/retry, and abort cleanup.

```ts
export interface AutosaveOptions {
  // Wait after edits settle, in milliseconds. Defaults to 500.
  delay?: number;
  // Whether new saves may start. Defaults to true; disabling does not undo an active write.
  enabled?: boolean;
  // Whether to save the initial value. Defaults to false.
  saveOnMount?: boolean;
}

export declare function useAutosave<
  // The type of the draft passed to the save callback.
  T
>(
  // The immutable draft value. Keep the reference stable until an edit actually changes it.
  value: T,
  // Async persistence callback receiving a captured draft and AbortSignal. Resolve only after saving succeeds.
  save: (value: T, signal: AbortSignal) => Promise<unknown>,
  // Debounce delay, enablement, and whether the initial value should be saved.
  { delay, enabled, saveOnMount }?: AutosaveOptions
):
  // Returns: Save status and a flush action that waits for queued edits.
  {
    // Save pending edits now and wait for newer queued edits too. Resolves true after successful draining, false on failure/disabled/unmounted state.
    flush: () => Promise<boolean>;
    // Whether edits are waiting or failed to save.
    dirty: boolean;
    // Whether a save callback is currently pending.
    saving: boolean;
    // The last save failure, or undefined when clear.
    error: unknown;
    // Timestamp of the last successful save in milliseconds since the Unix epoch, or undefined before success.
    lastSavedAt: number | undefined;
  };
```

</details>

## useRetry

**The status request gets three chances, not a lifetime membership**

A read-only status request may recover from a temporary network failure.

**Why this hook helps:** Retries are bounded and backoff waits are abortable; the result still uses async-task stale-response protection.

**Keep in mind:** Only retry operations that are safe to repeat. A payment submission is not automatically safe because a hook can retry it.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useRetry.tsx)

```tsx
'use client';

import { useRetry } from 'use-a-hook';

export default function ResilientStatusCheck() {
  const status = useRetry(
    async (signal) => {
      const response = await fetch('/api/service-status', { signal });
      if (!response.ok) throw new Error(`Status endpoint returned ${response.status}.`);
      return response.text();
    },
    { attempts: 3, delay: (attempt) => attempt * 500 },
  );
  return (
    <section>
      <button disabled={status.pending} onClick={() => void status.run()}>
        Check service status
      </button>
      <button disabled={!status.pending} onClick={status.cancel}>
        Cancel retries
      </button>
      <p>{status.data}</p>
      {status.status === 'error' && (
        <p role="alert">The status check failed after its allowed attempts.</p>
      )}
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Bounded retries for explicitly idempotent tasks, with abortable backoff.

```ts
export interface RetryOptions {
  // Maximum attempts including the first try. Defaults to 3; at least 1.
  attempts?: number;
  // Milliseconds before another attempt, or a function of the failed attempt number. Defaults to 300.
  delay?: number | ((attempt: number) => number);
  // Return false to stop retrying this error. Attempt numbers start at 1.
  shouldRetry?: (error: unknown, attempt: number) => boolean;
}

export declare function useRetry<
  // Argument types accepted by run and passed to each task attempt.
  A extends unknown[],
  // The successful task result type.
  T
>(
  // An async operation receiving AbortSignal first and then your arguments. Only retry work that is safe to repeat.
  task: (signal: AbortSignal, ...args: A) => Promise<T>,
  // Attempt limit, backoff delay, and a function deciding which errors can be retried.
  options?: RetryOptions
):
  // Returns: Async-task state and actions for a bounded retrying run.
  {
    // True only while the current task is running.
    pending: boolean;
    // Start a task with its arguments; a newer run cancels the previous signal. Failures/cancellation resolve to undefined and update status.
    run: (...args: A) => Promise<T | undefined>;
    // Cancel the current signal and clear its pending/error status; does not undo server work.
    cancel: () => void;
    // Cancel work and return to idle with no result or error.
    reset: () => void;
    // idle before work, pending while running, success after completion, or error after failure.
    status: "error" | "idle" | "pending" | "success";
    // The latest successful result; undefined before success or after a failed run.
    data: T | undefined;
    // The last failure value, or undefined when there is no failure.
    error: unknown;
  };
```

</details>

## useImage

**A thumbnail arrives before the curtain rises**

A theme preview checks whether its thumbnail is available before showing it in the card.

**Why this hook helps:** The hook preloads the image and exposes natural dimensions while ignoring replaced loads.

**Keep in mind:** Provide /theme-preview.png in your app. Preloading is not a replacement for responsive images or lazy-loading ordinary off-screen images.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useImage.tsx)

```tsx
'use client';

import { useImage } from 'use-a-hook';

export default function ThemeThumbnail() {
  const image = useImage('/theme-preview.png', {
    decode: true,
    referrerPolicy: 'no-referrer'
  });
  return (
    <figure>
      {image.status === 'loaded' ? (
        <img
          src="/theme-preview.png"
          alt="Theme preview"
          width={image.width}
          height={image.height}
        />
      ) : (
        <p role="status">
          {image.status === 'error'
            ? 'Preview image unavailable.'
            : 'Preparing preview image…'}
        </p>
      )}
    </figure>
  );
}
```

<details>
<summary>API signature</summary>

Race-safe image preloading with optional decode, request policy, and access to the loaded element.

```ts
export interface ImageOptions {
  // Optional anonymous or use-credentials request mode.
  crossOrigin?: 'anonymous' | 'use-credentials';
  // Optional image request referrer policy, set before src.
  referrerPolicy?: ReferrerPolicy;
  // Wait for image.decode() when supported. Defaults to false. Decode failure still allows an otherwise loaded image.
  decode?: boolean;
}

export interface ImageState {
  // idle without a source, loading while pending, loaded after success, or error after failure.
  status: 'idle' | 'loading' | 'loaded' | 'error';
  // Natural image width in pixels; undefined until loaded.
  width?: number;
  // Natural image height in pixels; undefined until loaded.
  height?: number;
  // An Error describing a failed load, or undefined otherwise.
  error?: Error;
  // The loaded HTMLImageElement, useful for canvas rendering; unavailable for stale or pending requests.
  image?: HTMLImageElement;
}

export declare function useImage(
  // The image URL to preload; null clears the request.
  src: string | null,
  // The original cross-origin string, or an options object with crossOrigin, referrerPolicy, and decode.
  crossOrigin?: 'anonymous' | 'use-credentials' | ImageOptions
):
  // Returns: Image loading state and natural dimensions, without inserting an img element.
  ImageState;
```

</details>

## useScript

**Invite the widget only when it is wanted**

A help panel needs a browser script, but the rest of the app should not load it before the panel is opened.

**Why this hook helps:** Consumers share a script tag and its loading state for the same URL and security attributes.

**Keep in mind:** Supply your own trusted /help-widget.js asset. Scripts remain cached for the document lifetime; closing the panel does not unload or sandbox their code.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useScript.tsx)

```tsx
'use client';

import { useState } from 'react';
import { useScript } from 'use-a-hook';

export default function OptionalHelpWidget() {
  const [open, setOpen] = useState(false);
  const status = useScript(open ? '/help-widget.js' : null);
  return (
    <section>
      <button aria-expanded={open} onClick={() => setOpen((value) => !value)}>
        Toggle help widget
      </button>
      {open && (
        <p role="status">
          Widget script: {status}. Your script owns its own widget initialization.
        </p>
      )}
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Share explicitly requested script elements and their loading state across consumers.

```ts
type Status = 'idle' | 'loading' | 'ready' | 'error';

export declare function useScript(
  // The script URL to load; null means no requested script.
  src: string | null,
  // Optional integrity, crossOrigin, and nonce attributes; together with src these identify the cached script.
  options?: {
    // Optional subresource-integrity value to verify the script contents.
    integrity?: string;
    // Optional cross-origin request mode for the script.
    crossOrigin?: 'anonymous' | 'use-credentials';
    // Optional nonce matching the application Content Security Policy.
    nonce?: string;
  }
):
  // Returns: idle with no source, loading while downloading, ready after load, or error after failure. Tags stay cached for the document lifetime.
  Status;

export {};
```

</details>

## useDirty

**The form knows which receipt is the saved one**

A profile editor marks local changes as unsaved until the user accepts the current value as its baseline.

**Why this hook helps:** Dirty state compares the current value with an explicit saved baseline, without serializing the whole form on every render.

**Keep in mind:** Call markClean only after persistence succeeds in a real app. This example accepts a local preview baseline.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useDirty.tsx)

```tsx
'use client';

import { useState } from 'react';
import { useDirty } from 'use-a-hook';

export default function DisplayNameDraft() {
  const [name, setName] = useState('Ada');
  const draft = useDirty(name);
  return (
    <section>
      <input
        aria-label="Display name"
        value={name}
        onChange={(event) => setName(event.target.value)}
      />
      <button disabled={!draft.dirty} onClick={() => draft.markClean(name)}>
        Accept local baseline
      </button>
      <p>
        {draft.dirty
          ? 'Local changes differ from the baseline.'
          : 'Matches the accepted baseline.'}
      </p>
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Track an editable value against an explicitly accepted baseline.

```ts
export declare function useDirty<
  // The shared type of the current value and its baseline.
  T
>(
  // The value currently being edited.
  value: T,
  // Optional comparison function. Defaults to Object.is, so object references should remain stable between edits.
  equal?: (a: T, b: T) => boolean
):
  // Returns: Whether the value differs from the accepted baseline, and an action to accept a saved value.
  {
    // True when value and baseline are not considered equal.
    dirty: boolean;
    // The initial or most recently accepted saved value.
    baseline: T;
    // Accept a value as the new saved baseline; call after successful persistence.
    markClean: (next: T) => void;
  };
```

</details>

## useValidation

**A tiny bouncer for a single rule**

A workspace slug must use lowercase letters, numbers, and dashes.

**Why this hook helps:** The hook derives a validation result from the current value and a caller-owned pure validator.

**Keep in mind:** Keep validators stable for memoization. Server validation still decides what can actually be saved.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useValidation.tsx)

```tsx
'use client';

import { useState } from 'react';
import { useValidation } from 'use-a-hook';

<details>
<summary>API signature</summary>

Memoized synchronous validation with caller-defined rules and error shape.

```ts
export declare function useValidation<
  // The value type passed to your validator.
  T,
  // The validator result type; it is returned without changing its shape.
  E
>(
  // The value to validate.
  value: T,
  // A pure rule function returning your chosen result, such as an error string or undefined.
  validate: (value: T) => E
):
  // Returns: The memoized validation result. The hook does not choose an error shape or contact the server.
  E;
```

</details>

## useField

**One field brings its own clipboard**

A settings field needs a value, a touched flag, a validation message, and a reset button.

**Why this hook helps:** The hook keeps these small field concerns together without imposing a form renderer.

**Keep in mind:** Touched state controls when you show feedback. A field being valid locally does not guarantee its value is accepted by the server.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useField.tsx)

```tsx
'use client';

import { useField } from 'use-a-hook';

<details>
<summary>API signature</summary>

Headless field value, touched state, validation, and original-value reset.

```ts
export declare function useField<
  // The field value type. Specify it explicitly when needed, for example useField<string>.
  T
>(
  // The original field value; reset restores this captured value.
  initial: T,
  // Optional synchronous rule: return an error string, or undefined for a valid value.
  validate?: (value: T) => string | undefined
):
  // Returns: Field state, validation feedback, and edit/reset actions.
  {
    // The current field value.
    value: T;
    // Set the value directly or calculate it from the previous value.
    setValue: import("react").Dispatch<import("react").SetStateAction<T>>;
    // Whether the field has been marked as visited.
    touched: boolean;
    // Set the touched flag directly or from its previous value.
    setTouched: import("react").Dispatch<import("react").SetStateAction<boolean>>;
    // The validation message, or undefined when no error exists.
    error: string | undefined;
    // True only when error is undefined; an empty error string still counts as invalid.
    valid: boolean;
    // Marks the field touched; pass it to the input blur handler.
    onBlur: () => void;
    // Restore the original value and clear touched state.
    reset: () => void;
  };
```

</details>

## useForm

**A small form with labeled drawers**

A team-creation preview manages a name and seat count together.

**Why this hook helps:** Typed field updates, touched flags, synchronous errors, and reset cover a small headless form without a large framework.

**Keep in mind:** Use a dedicated form library for large nested forms or field arrays. This example intentionally does not send data to a server.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useForm.tsx)

```tsx
'use client';

import { useForm } from 'use-a-hook';

type Team = { name: string; seats: number };
const validate = (values: Team) => ({
  name: values.name.trim() ? undefined : 'Name is required.',
  seats: values.seats >= 1 ? undefined : 'Choose at least one seat.',
});
export default function TeamFormPreview() {
  const form = useForm<Team>({ name: '', seats: 1 }, validate);
  return (
    <form onSubmit={(event) => event.preventDefault()}>
      <label>
        Team name{' '}
        <input
          value={form.values.name}
          onChange={(event) => form.setField('name', event.target.value)}
          onBlur={() => form.touch('name')}
        />
      </label>
      {form.touched.name && form.errors.name && <p role="alert">{form.errors.name}</p>}
      <label>
        Seats{' '}
        <input
          type="number"
          min={1}
          value={form.values.seats}
          onChange={(event) => form.setField('seats', Number(event.target.value))}
        />
      </label>
      <button type="submit" disabled={!form.valid}>
        Preview valid team
      </button>
      <button type="button" onClick={form.reset}>
        Reset
      </button>
    </form>
  );
}
```

<details>
<summary>API signature</summary>

Small headless forms with typed field updates, touched fields, validation, and reset.

```ts
export type FormErrors<T> = Partial<Record<keyof T, string | undefined>>;

export declare function useForm<
  // The object shape of your form; its keys become valid field names.
  T extends object
>(
  // The initial object of field values, captured for reset.
  initial: T,
  // Optional synchronous function returning error messages keyed by field name; undefined means no error for that field.
  validate?: (values: T) => FormErrors<T>
):
  // Returns: Typed form values, field errors, touched flags, and update actions.
  {
    // The current form object.
    values: T;
    // Replace the whole form object or calculate it from the previous object.
    setValues: import("react").Dispatch<import("react").SetStateAction<T>>;
    // Update one field; its value type must match that field in T.
    setField: <K extends keyof T>(key: K, value: T[K]) => void;
    // An optional true/false visited flag for each field.
    touched: Partial<Record<keyof T, boolean>>;
    // Mark a field as visited.
    touch: (key: keyof T) => void;
    // Optional error messages keyed by field name; absent or undefined means no error.
    errors: Partial<Record<keyof T, string | undefined>>;
    // True when every field error is undefined.
    valid: boolean;
    // Restore initial values and clear touched flags.
    reset: () => void;
  };
```

</details>

## useSubmit

**The invite button refuses a double order**

A team invitation form should not send a second request just because someone double-clicked before React updated the button.

**Why this hook helps:** A synchronous in-flight lock ignores duplicate submissions while the first task is pending.

**Keep in mind:** Your app implements /api/team-invitations and must enforce authorization and idempotency. A UI lock is not a server-side duplicate guarantee.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useSubmit.tsx)

```tsx
'use client';

import { useState } from 'react';
import { useSubmit } from 'use-a-hook';

export default function InviteTeammate() {
  const [email, setEmail] = useState('');
  const invite = useSubmit(async (signal, address: string) => {
    const response = await fetch('/api/team-invitations', {
      method: 'POST',
      signal,
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email: address }),
    });
    if (!response.ok) throw new Error('Invitation failed.');
    return address;
  });
  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        void invite.run(email);
      }}
    >
      <label>
        Email{' '}
        <input
          type="email"
          required
          value={email}
          onChange={(event) => setEmail(event.target.value)}
        />
      </label>
      <button disabled={invite.pending}>Send invitation</button>
      {invite.status === 'success' && (
        <p role="status">Invitation sent to {invite.data}.</p>
      )}
      {invite.status === 'error' && <p role="alert">Could not send the invitation.</p>}
    </form>
  );
}
```

<details>
<summary>API signature</summary>

Ignore duplicate submissions while one task is running; expose pending and error state.

```ts
export declare function useSubmit<
  // The input argument types passed to run.
  A extends unknown[],
  // The successful submission result type.
  T
>(
  // Async submission receiving AbortSignal first, then your input arguments. It should settle and honor cancellation.
  submit: (signal: AbortSignal, ...args: A) => Promise<T>
):
  // Returns: Async-task state with a run action that ignores duplicate calls while one submission is active.
  {
    // Submit once; calls made before the active submission settles are ignored. Inspect status for success or failure.
    run: (...args: A) => Promise<T | undefined>;
    // True only while the current task is running.
    pending: boolean;
    // Cancel the current signal and clear its pending/error status; does not undo server work.
    cancel: () => void;
    // Cancel work and return to idle with no result or error.
    reset: () => void;
    // idle before work, pending while running, success after completion, or error after failure.
    status: "error" | "idle" | "pending" | "success";
    // The latest successful result; undefined before success or after a failed run.
    data: T | undefined;
    // The last failure value, or undefined when there is no failure.
    error: unknown;
  };
```

</details>

## useUnsavedChanges

**The tab gets a “you forgot your draft” sign**

An editor warns about leaving the browser page while local work is marked dirty.

**Why this hook helps:** The unload listener exists only while there are unsaved changes, and cleanup removes it when the draft becomes clean.

**Keep in mind:** Browsers control whether the prompt appears and what it says. Client-side route blocking needs integration with your router.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useUnsavedChanges.tsx)

```tsx
'use client';

import { useState } from 'react';
import { useUnsavedChanges } from 'use-a-hook';

export default function DraftExitWarning() {
  const [note, setNote] = useState('');
  const [accepted, setAccepted] = useState('');
  const dirty = note !== accepted;
  useUnsavedChanges(dirty);
  return (
    <section>
      <textarea
        aria-label="Draft"
        value={note}
        onChange={(event) => setNote(event.target.value)}
      />
      <button onClick={() => setAccepted(note)}>Accept local preview</button>
      <p>
        {dirty
          ? 'Unsaved preview edits: closing the page may show a browser warning.'
          : 'Preview is clean.'}
      </p>
    </section>
  );
}
```

<details>
<summary>API signature</summary>

```ts
export declare function useUnsavedChanges(
  // Whether there are unsaved changes requiring a browser unload prompt.
  dirty: boolean
):
  // Returns: Nothing to store: attaches beforeunload only while dirty. Browsers control prompt behavior; SPA route blocking is separate.
  void;
```

</details>

## useConfirm

**The delete button checks its manners**

A destructive action waits for an explicit yes or no instead of firing on the first click.

**Why this hook helps:** The hook exposes a confirmation request and a Promise. Replacing or unmounting an unanswered request resolves it as false.

**Keep in mind:** This example uses a native dialog for focus and modal behavior. The hook itself does not render or trap focus.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useConfirm.tsx)

```tsx
'use client';

import { useState, useRef, useEffect } from 'react';
import { useConfirm } from 'use-a-hook';

export default function DeleteDraftConfirmation() {
  const confirmation = useConfirm();
  const dialog = useRef<HTMLDialogElement>(null);
  const [deleted, setDeleted] = useState(false);
  useEffect(() => {
    const node = dialog.current;
    if (!node) return;
    if (confirmation.open && !node.open) node.showModal();
    else if (!confirmation.open && node.open) node.close();
  }, [confirmation.open]);
  async function remove() {
    if (
      await confirmation.confirm({
        title: 'Delete this local draft?',
        description: 'Only this preview changes.',
      })
    )
      setDeleted(true);
  }
  return (
    <section>
      <button disabled={deleted} onClick={() => void remove()}>
        Delete local draft
      </button>
      <p>{deleted ? 'Local draft deleted.' : 'Local draft is still here.'}</p>
      <dialog
        ref={dialog}
        aria-labelledby="confirm-title"
        onCancel={(event) => {
          event.preventDefault();
          confirmation.resolve(false);
        }}
        onClose={() => confirmation.resolve(false)}
      >
        <h2 id="confirm-title">{confirmation.request?.title}</h2>
        <p>{confirmation.request?.description}</p>
        <button onClick={() => confirmation.resolve(false)}>Keep it</button>
        <button onClick={() => confirmation.resolve(true)}>Delete draft</button>
      </dialog>
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Headless promise-based confirmation; replacement and unmount resolve pending requests as false.

```ts
export interface ConfirmOptions {
  // The question shown to the user.
  title: string;
  // Optional extra explanation for the decision.
  description?: string;
  // Optional text for the confirmation button; the app must render it.
  confirmLabel?: string;
  // Optional text for the cancellation button; the app must render it.
  cancelLabel?: string;
}

export declare function useConfirm():
  // Returns: A headless confirmation request and actions. Your app renders the dialog.
  {
    // The currently displayed request options, or null when closed.
    request: ConfirmOptions | null;
    // Whether a confirmation is waiting for an answer.
    open: boolean;
    // Open a request and await true for approval or false for cancellation. Replacing/unmounting resolves an old request as false.
    confirm: (options: ConfirmOptions) => Promise<boolean>;
    // Answer the current request with true or false and close it.
    resolve: (confirmed: boolean) => void;
  };
```

</details>

## useRequiredContext

**A component asks for its backstage pass**

A workspace toolbar needs settings from its provider and should fail clearly if someone mounts it outside that provider.

**Why this hook helps:** The hook reads context and replaces a distant null-property crash with a useful missing-provider error.

**Keep in mind:** This does not narrow context subscriptions. Split contexts or use a stable external store if unrelated changes cause too many renders.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useRequiredContext.tsx)

```tsx
'use client';

import { createContext } from 'react';
import { useRequiredContext } from 'use-a-hook';

<details>
<summary>API signature</summary>

Read a required provider value and fail clearly when its provider is missing.

```ts
import { type Context } from 'react';

export declare function useRequiredContext<
  // The context value type, possibly including null or undefined for the missing-provider case.
  T
>(
  // The React context to read. Null and undefined mean its required provider is missing.
  context: Context<T>,
  // The provider name to include in the error message. Defaults to Required provider.
  providerName?: string
):
  // Returns: The non-null context value. Throws a clear error when no required value is available.
  NonNullable<T>;
```

</details>

## useStoreSelector

**Subscribe to your desk, not the whole office**

A cart badge needs only the item count from a larger external store.

**Why this hook helps:** A selector and equality check keep unrelated store updates from publishing a new selected value.

**Keep in mind:** Snapshots must be immutable and cached. This example creates a store per component instance; avoid sharing mutable account state across server requests.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useStoreSelector.tsx)

```tsx
'use client';

import { useConstant, useStoreSelector } from 'use-a-hook';

<details>
<summary>API signature</summary>

Subscribe to an external store and reuse selected values when equality succeeds.

```ts
export declare function useStoreSelector<
  // The complete store state type.
  S,
  // The selected value type, which may be smaller than the full state.
  T
>(
  // Register a change listener and return an unsubscribe function. Keep this function stable.
  subscribe: (notify: () => void) => () => void,
  // Read the current immutable, cached store state.
  getSnapshot: () => S,
  // Pick the part of store state this component needs.
  selector: (state: S) => T,
  // Optional server/initial hydration snapshot reader; supply it when server rendering.
  getServerSnapshot?: () => S,
  // Compare selected values. Defaults to Object.is; return true to reuse the previous selected value.
  equal?: (a: T, b: T) => boolean
):
  // Returns: The selected store value; unrelated changes can reuse the previous selection.
  T;
```

</details>

## useTheme

**Light, dark, or let the device pick its pajamas**

A workspace preference offers light, dark, and system appearance choices.

**Why this hook helps:** The hook distinguishes the saved preference from the resolved system appearance and can apply document attributes.

**Keep in mind:** Supply CSS for data-theme yourself. Use one app-level owner/provider, and compose useLocalStorage if the preference should persist.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useTheme.tsx)

```tsx
'use client';

import { useTheme } from 'use-a-hook';

export default function AppearanceSwitcher() {
  const appearance = useTheme({ defaultValue: 'system', applyToDocument: true });
  return (
    <section>
      <label>
        Appearance{' '}
        <select
          value={appearance.theme}
          onChange={(event) => {
            const next = event.target.value;
            if (next === 'light' || next === 'dark' || next === 'system')
              appearance.setTheme(next);
          }}
        >
          <option value="system">Use device setting</option>
          <option value="light">Light</option>
          <option value="dark">Dark</option>
        </select>
      </label>
      <p>
        Resolved appearance: {appearance.resolvedTheme}. Add styles for [data-theme] in
        your app.
      </p>
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Controlled or local light/dark/system preference with optional document application.

```ts
export type ThemePreference = 'light' | 'dark' | 'system';

export interface ThemeOptions {
  // Optional controlled preference. Omit it for local state.
  value?: ThemePreference;
  // Initial local preference. Defaults to system.
  defaultValue?: ThemePreference;
  // Called when a new preference is requested; update controlled value in the owner.
  onChange?: (value: ThemePreference) => void;
  // When true, update document data-theme and color-scheme. Defaults to false; use one document owner.
  applyToDocument?: boolean;
}

export declare function useTheme(
  // Choose controlled or local theme state and optional document updates.
  options?: ThemeOptions
):
  // Returns: The chosen theme preference, its resolved appearance, and a setter.
  {
    // The preference: light, dark, or system.
    theme: ThemePreference;
    // The actual light/dark appearance after resolving a system preference.
    resolvedTheme: "light" | "dark";
    // Request a preference directly or from the previous preference. Controlled state still belongs to its owner.
    setTheme: (action: import("react").SetStateAction<ThemePreference>) => void;
  };
```

</details>

## useLocale

**The language switcher changes the name tag**

A settings preview lets the user switch language and updates document language/direction when it owns that responsibility.

**Why this hook helps:** Locale tags are canonicalized, while optional document updates keep lang and dir aligned with the selected locale.

**Keep in mind:** The hook does not translate copy or persist preferences by itself. Use a shared provider and your own translation dictionaries.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useLocale.tsx)

```tsx
'use client';

import { useLocale } from 'use-a-hook';

export default function LanguageSwitcher() {
  const language = useLocale({ defaultValue: 'en', applyToDocument: true });
  return (
    <section>
      <label>
        Language{' '}
        <select
          value={language.locale}
          onChange={(event) => language.setLocale(event.target.value)}
        >
          <option value="en">English</option>
          <option value="my">မြန်မာ</option>
          <option value="ar">العربية</option>
        </select>
      </label>
      <p>
        Locale: {language.locale}; direction: {language.direction}.
      </p>
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Controlled or local canonical language selection, with optional document language and direction.

```ts
export interface LocaleOptions {
  // Optional parent-controlled locale tag.
  value?: string;
  // Initial local locale. Defaults to en.
  defaultValue?: string;
  // Called when a new locale is requested; the owner must update controlled value.
  onChange?: (locale: string) => void;
  // When true, update document lang and dir. Defaults to false; use one document owner.
  applyToDocument?: boolean;
}

export declare function useLocale(
  // Choose controlled or local language state and optional document updates.
  options?: LocaleOptions
):
  // Returns: A canonical locale tag, reading direction, and a setter.
  {
    // The canonical language tag, such as en-US or my.
    locale: string;
    // The resolved text direction: ltr or rtl.
    direction: "ltr" | "rtl";
    // Choose a valid locale tag; invalid locale tags throw a RangeError.
    setLocale: (next: string) => void;
  };
```

</details>

## useTranslation

**Hello, hola, and no mystery placeholders**

A welcome panel picks a dictionary string and inserts the user’s name.

**Why this hook helps:** Dictionary lookup supports an exact locale, a base-language fallback, a fallback locale, and simple named interpolation.

**Keep in mind:** This is plain-text interpolation, not an ICU plural engine or HTML renderer. Keep message dictionaries stable across renders.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useTranslation.tsx)

```tsx
'use client';

import { useState } from 'react';
import { useTranslation } from 'use-a-hook';

<details>
<summary>API signature</summary>

Dictionary lookup with fallback locale and simple named interpolation; no bundled locale data.

```ts
export type TranslationMessages = Readonly<Record<string, Readonly<Record<string, string>>>>;

export declare function useTranslation(
  // Dictionaries keyed by locale, then message key. Keep them stable across renders.
  messages: TranslationMessages,
  // The locale to try first; its base language is tried next.
  locale: string,
  // The final dictionary to try. Defaults to en.
  fallbackLocale?: string
):
  // Returns: A function taking a message key and optional named values. Missing messages fall back to the key itself.
  (key: string, values?: Record<string, string | number>) => string;
```

</details>

## useNumberFormat

**Money gets dressed for the neighborhood**

A pricing preview formats the same USD amount using the selected locale’s separators and currency placement.

**Why this hook helps:** Memoized Intl.NumberFormat instances avoid reconstructing a formatter for every cell or render.

**Keep in mind:** Formatting changes presentation, not exchange rates. Choose the actual billing currency from your business data.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useNumberFormat.tsx)

```tsx
'use client';

import { useState } from 'react';
import { useNumberFormat } from 'use-a-hook';

export default function LocalizedPrice() {
  const [locale, setLocale] = useState('en-US');
  const money = useNumberFormat(locale, { style: 'currency', currency: 'USD' });
  return (
    <section>
      <select
        aria-label="Formatting locale"
        value={locale}
        onChange={(event) => setLocale(event.target.value)}
      >
        <option value="en-US">English (US)</option>
        <option value="de-DE">Deutsch</option>
      </select>
      <p>Monthly plan: {money.format(1299.5)}</p>
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Memoize an Intl number formatter for currency, percentages, and quantities.

```ts
export declare function useNumberFormat(
  // The formatting locale. Defaults to en; this does not convert currencies.
  locale?: string,
  // Browser Intl.NumberFormat options, such as style, currency, and maximumFractionDigits.
  options?: Intl.NumberFormatOptions
):
  // Returns: A reusable number formatter. Call format(value), for example money.format(29.99).
  Intl.NumberFormat;
```

</details>

## useDateTimeFormat

**The meeting time keeps its passport**

A support console shows the same scheduled timestamp in a selected time zone.

**Why this hook helps:** The hook reuses an Intl.DateTimeFormat instance while locale and formatting options stay equivalent.

**Keep in mind:** Supply a consistent time zone for server/client rendering. Formatting a timestamp does not schedule or move the underlying meeting.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useDateTimeFormat.tsx)

```tsx
'use client';

import { useState } from 'react';
import { useDateTimeFormat } from 'use-a-hook';

<details>
<summary>API signature</summary>

Memoize date/time formatting with caller-controlled locale and time zone.

```ts
export declare function useDateTimeFormat(
  // The formatting locale. Defaults to en.
  locale?: string,
  // Browser Intl.DateTimeFormat settings. Set timeZone explicitly for matching server/client output.
  options?: Intl.DateTimeFormatOptions
):
  // Returns: A reusable date/time formatter. Call format(dateOrTimestamp).
  Intl.DateTimeFormat;
```

</details>

## useRelativeTime

**“Yesterday” sounds friendlier than timestamp soup**

An activity preview describes an event as yesterday, today, or several days ago.

**Why this hook helps:** A reusable Intl.RelativeTimeFormat handles language-specific relative phrasing.

**Keep in mind:** The formatter does not run a clock. Combine it with useNow when the relative value must advance automatically.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useRelativeTime.tsx)

```tsx
'use client';

import { useState } from 'react';
import { useRelativeTime } from 'use-a-hook';

export default function RelativeActivityLabel() {
  const [days, setDays] = useState(-1);
  const relative = useRelativeTime('en', { numeric: 'auto' });
  return (
    <section>
      <label>
        Days from today{' '}
        <input
          type="number"
          value={days}
          onChange={(event) => setDays(Number(event.target.value))}
        />
      </label>
      <p>Report activity: {relative.format(days, 'day')}</p>
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Memoize relative-time formatting such as yesterday and in three days.

```ts
export declare function useRelativeTime(
  // The language used for relative labels. Defaults to en.
  locale?: string,
  // Browser relative-time settings. Defaults to numeric: auto, allowing labels such as yesterday.
  options?: Intl.RelativeTimeFormatOptions
):
  // Returns: A reusable relative-time formatter. Call format(amount, unit), for example format(-1, day). It does not run a clock.
  Intl.RelativeTimeFormat;
```

</details>

## useCollator

**File 2 belongs before File 10**

A document picker sorts names using natural numeric comparison rather than placing File 10 before File 2.

**Why this hook helps:** Intl.Collator provides a locale-aware comparator that can be reused across sorting operations.

**Keep in mind:** Choose options deliberately: case sensitivity, numeric ordering, and locale can change which order users expect.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useCollator.tsx)

```tsx
'use client';

import { useCollator, useSortedList } from 'use-a-hook';

<details>
<summary>API signature</summary>

Memoize locale-aware string comparison for sorting and search matching.

```ts
export declare function useCollator(
  // The language rules to use for comparing text. Defaults to en.
  locale?: string,
  // Browser comparison settings, such as numeric: true for File 2 before File 10.
  options?: Intl.CollatorOptions
):
  // Returns: A reusable text comparator. Pass its compare function to a sorting operation.
  Intl.Collator;
```

</details>

## useTextDirection

**The layout knows which way to read**

A multilingual preview sets reading direction for English or Arabic content.

**Why this hook helps:** Direction comes from locale/script metadata, with an explicit override available for special cases.

**Keep in mind:** Prefer CSS logical properties such as padding-inline-start so the layout can adapt without hand-written left/right swaps.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useTextDirection.tsx)

```tsx
'use client';

import { useState } from 'react';
import { useTextDirection } from 'use-a-hook';

export default function ReadingDirectionPreview() {
  const [locale, setLocale] = useState('en');
  const direction = useTextDirection(locale);
  return (
    <section>
      <select
        aria-label="Preview language"
        value={locale}
        onChange={(event) => setLocale(event.target.value)}
      >
        <option value="en">English</option>
        <option value="ar">العربية</option>
      </select>
      <article dir={direction} style={{ paddingInlineStart: 16 }}>
        <p>
          {locale === 'ar' ? 'مرحباً بكم في مساحة العمل' : 'Welcome to the workspace'}
        </p>
      </article>
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Resolve text direction from locale/script metadata, with an explicit override.

```ts
export declare function useTextDirection(
  // A valid locale tag whose language/script determines the default reading direction.
  locale: string,
  // Optional explicit ltr or rtl value; takes priority over locale.
  override?: 'ltr' | 'rtl'
):
  // Returns: ltr for left-to-right text, or rtl for right-to-left text.
  'ltr' | 'rtl';
```

</details>

## useDisclosure

**A drawer with labeled handles**

A project card reveals an optional description with explicit open, close, and toggle actions.

**Why this hook helps:** Named actions make event intent clearer than scattering boolean setters throughout a component.

**Keep in mind:** This hook owns open state only. Focus trapping, dialogs, menus, and animation are separate responsibilities.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useDisclosure.tsx)

```tsx
'use client';

import { useDisclosure } from 'use-a-hook';

export default function ProjectDescription() {
  const details = useDisclosure();
  return (
    <section>
      <button aria-expanded={details.isOpen} onClick={details.toggle}>
        Project details
      </button>
      {details.isOpen && (
        <aside>
          <p>A small redesign with a surprisingly large mood board.</p>
          <button onClick={details.close}>Close details</button>
        </aside>
      )}
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Explicit open/close/toggle actions for headless dialogs, menus, and drawers.

```ts
export declare function useDisclosure(
  // Whether the surface starts open. Defaults to false.
  initialOpen?: boolean
):
  // Returns: The open state and explicit open/close/toggle actions.
  {
    // Whether the surface should be shown.
    isOpen: boolean;
    // Set the surface to open.
    open: () => void;
    // Set the surface to closed.
    close: () => void;
    // Flip open to closed or closed to open.
    toggle: () => void;
    // Set the boolean directly or calculate it from the previous boolean.
    setOpen: import("react").Dispatch<import("react").SetStateAction<boolean>>;
  };
```

</details>

## useTabs

**The settings room has two labeled doors**

A settings screen switches between profile and billing panels with mouse and keyboard navigation.

**Why this hook helps:** The hook connects tab/panel IDs, selected state, arrow-key activation, and roving focus.

**Keep in mind:** Render the tablist role and meaningful labels yourself. This implementation uses horizontal automatic activation.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useTabs.tsx)

```tsx
'use client';

import { useTabs } from 'use-a-hook';

<details>
<summary>API signature</summary>

Headless tab/panel props with arrow navigation, linked ARIA IDs, and roving focus.

```ts
import { type KeyboardEvent } from 'react';

export declare function useTabs<
  // The allowed tab ID strings. A literal array can restrict selection to known IDs.
  T extends string
>(
  // Stable tab IDs in display order; pass a nonempty list for a usable tab group.
  ids: readonly T[],
  // The initially selected tab ID. Defaults to the first supplied ID.
  initialId?: T
):
  // Returns: Selection state and props to spread onto tab buttons and panels.
  {
    // The selected tab ID; at runtime undefined if the supplied ID list is empty.
    active: T;
    // Select an ID from the supplied list.
    select: (id: T) => void;
    // Get a tab button ref, ARIA attributes, selected tabIndex, and click/arrow-key handlers.
    getTabProps: (id: T) => {
      // Accessibility role to spread onto the tab or panel.
      role: "tab";
      // Generated element ID that links a tab with its panel.
      id: string;
      // Tells assistive technology whether this tab is selected.
      'aria-selected': boolean;
      // The ID of the panel controlled by this tab.
      'aria-controls': string;
      // Keyboard tab order: 0 is reachable with Tab; -1 is reachable through code.
      tabIndex: number;
      // Attach to the tab element so arrow keys can move keyboard focus.
      ref: (node: HTMLElement | null) => void;
      // Select this tab when it is clicked.
      onClick: () => void;
      // Move between tabs with arrow keys, Home, and End.
      onKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
    };
    // Get matching panel IDs, ARIA labels, hidden state, and tabIndex.
    getPanelProps: (id: T) => {
      // Accessibility role to spread onto the tab or panel.
      role: "tabpanel";
      // Generated element ID that links a tab with its panel.
      id: string;
      // The ID of the tab that labels this panel.
      'aria-labelledby': string;
      // Hide this panel when its tab is inactive.
      hidden: boolean;
      // Keyboard tab order: 0 is reachable with Tab; -1 is reachable through code.
      tabIndex: number;
    };
  };
```

</details>

## useStepper

**The wizard puts numbers on its doors**

An onboarding preview walks through team details, preferences, and a final review.

**Why this hook helps:** Clamped navigation keeps the active step within bounds and exposes progress and first/last flags.

**Keep in mind:** Moving to the next step does not validate or save it. Complete those tasks before advancing in a real onboarding flow.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useStepper.tsx)

```tsx
'use client';

import { useStepper } from 'use-a-hook';

<details>
<summary>API signature</summary>

Clamped step navigation and progress for onboarding and setup wizards.

```ts
export declare function useStepper(
  // The total number of steps, clamped to at least 1.
  steps: number,
  // The starting zero-based step index. Defaults to 0.
  initialStep?: number
):
  // Returns: A clamped step index and navigation/progress helpers.
  {
    // The current step index, starting at 0.
    step: number;
    // The total number of steps.
    count: number;
    // True on the first step.
    isFirst: boolean;
    // True on the final step.
    isLast: boolean;
    // Completion position from 0 to 1; the first of three steps reports 1/3.
    progress: number;
    // Go to a zero-based step index, clamped to the available range.
    goTo: (next: number) => void;
    // Move forward one step if possible.
    next: () => void;
    // Move back one step if possible.
    previous: () => void;
    // Return to step index 0.
    reset: () => void;
  };
```

</details>

## useAccordion

**The FAQ opens one filing drawer at a time**

A billing FAQ lets one answer stay expanded at a time.

**Why this hook helps:** Stable item IDs track expansion without coupling the state to a particular accordion renderer.

**Keep in mind:** Add aria-expanded, aria-controls, and matching panel IDs. Keep IDs unique if you mount multiple copies of this example.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useAccordion.tsx)

```tsx
'use client';

import { useAccordion } from 'use-a-hook';

<details>
<summary>API signature</summary>

Headless single/multiple expanded-item state using stable item IDs.

```ts
export declare function useAccordion<
  // The type of stable panel IDs.
  T
>(
  // IDs of panels that start expanded. Defaults to none.
  initial?: readonly T[],
  // Whether several panels may be open. Defaults to true; false keeps one newly opened panel at a time.
  multiple?: boolean
):
  // Returns: Expanded panel IDs and actions; your app supplies the rendered markup.
  {
    // The read-only set of expanded panel IDs.
    expanded: ReadonlySet<T>;
    // Open a closed panel or close an open panel.
    toggle: (id: T) => void;
    // Close every panel.
    collapseAll: () => void;
    // Check whether one panel ID is currently expanded.
    isExpanded: (id: T) => boolean;
  };
```

</details>

## useRovingFocus

**One Tab stop, several useful buttons**

A formatting toolbar lets Tab enter the group once and arrow keys move between its controls.

**Why this hook helps:** The hook manages tabIndex and arrow/Home/End focus movement for an enabled item list.

**Keep in mind:** Focus is not the same as activation. Keep actions on normal click handlers and exclude disabled controls from the managed list.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useRovingFocus.tsx)

```tsx
'use client';

import { useState } from 'react';
import { useRovingFocus } from 'use-a-hook';

<details>
<summary>API signature</summary>

One tab stop with arrow/Home/End navigation for toolbars and item groups.

```ts
import { type KeyboardEvent } from 'react';

export declare function useRovingFocus(
  // The number of enabled items in the focus group.
  count: number,
  // Arrow-key direction, looping, and the initial item index.
  options?: {
    // horizontal uses Left/Right; vertical uses Up/Down. Defaults to horizontal.
    orientation?: 'horizontal' | 'vertical';
    // Whether arrow navigation wraps at the ends. Defaults to true.
    loop?: boolean;
    // The first active item index. Defaults to 0.
    initialIndex?: number;
  }
):
  // Returns: The active focus index and props for each item.
  {
    // The item with tabIndex 0; -1 when the group is empty.
    activeIndex: number;
    // Set the requested zero-based focus index directly or from the previous index.
    setActiveIndex: import("react").Dispatch<import("react").SetStateAction<number>>;
    // Get an item ref, tabIndex, focus listener, and arrow/Home/End handlers. Spread these onto an enabled control.
    getItemProps: (index: number) => {
      // Only the active item has tabIndex=0; the others use -1.
      tabIndex: number;
      // Attach to the item element so the hook can move keyboard focus.
      ref: (node: HTMLElement | null) => void;
      // Make this item active when it receives focus.
      onFocus: () => void;
      // Handle arrow keys, Home, and End to move focus between items.
      onKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
    };
  };
```

</details>

## useFocusReturn

**The search panel returns you to your seat**

A temporary search panel moves focus into its input, then restores focus to the opener when closed.

**Why this hook helps:** The hook remembers the previously focused element while the surface is active and restores it on cleanup.

**Keep in mind:** This is focus restoration, not focus trapping. Use a proper modal primitive for a modal dialog.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useFocusReturn.tsx)

```tsx
'use client';

import { useState, useRef, useEffect } from 'react';
import { useFocusReturn } from 'use-a-hook';

export default function SearchWithFocusReturn() {
  const [open, setOpen] = useState(false);
  const input = useRef<HTMLInputElement>(null);
  useFocusReturn(open);
  useEffect(() => {
    if (open) input.current?.focus();
  }, [open]);
  return (
    <section>
      <button aria-expanded={open} onClick={() => setOpen(true)}>
        Open search panel
      </button>
      {open && (
        <aside aria-label="Search panel">
          <input ref={input} aria-label="Search workspace" />
          <button onClick={() => setOpen(false)}>Close and return focus</button>
        </aside>
      )}
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Restore the previously focused element when an active surface closes.

```ts
export declare function useFocusReturn(
  // Whether the temporary surface is active. When it closes, focus returns to the previously focused connected element.
  active: boolean
):
  // Returns: Nothing to store: this restores focus but does not trap focus or open a modal.
  void;
```

</details>

## useLongPress

**The button waits for a deliberate hold**

A media-review preview offers extra actions after a deliberate pointer or keyboard hold.

**Why this hook helps:** The hook detects the hold threshold and cancels when the pointer moves too far, leaves, or releases.

**Keep in mind:** Always provide an ordinary accessible way to reach the same actions. Timing gestures should be shortcuts, not the only entrance.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useLongPress.tsx)

```tsx
'use client';

import { useState } from 'react';
import { useLongPress } from 'use-a-hook';

export default function HoldForActions() {
  const [shown, setShown] = useState(false);
  const press = useLongPress(() => setShown(true), { delay: 600 });
  return (
    <section>
      <button {...press.handlers} onClick={() => setShown(true)}>
        Hold or click to show review actions
      </button>
      {shown && (
        <div>
          <p>Review actions: approve, comment, or return to draft.</p>
          <button onClick={() => setShown(false)}>Hide actions</button>
        </div>
      )}
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Pointer and keyboard long-press detection with cancellation and timer cleanup.

```ts
import { type PointerEvent, type KeyboardEvent } from 'react';

export declare function useLongPress(
  // The action after a pointer or Space/Enter key is held long enough.
  callback: () => void,
  // Hold duration, enablement, and allowed pointer movement.
  options?: {
    // Hold duration in milliseconds. Defaults to 500.
    delay?: number;
    // Whether holds are ignored. Defaults to false.
    disabled?: boolean;
    // Maximum movement before cancelling a hold, in CSS pixels. Defaults to 10.
    movementTolerance?: number;
  }
):
  // Returns: Long-press state, cancellation, and handlers to spread onto a control.
  {
    // True after the hold threshold fires, until release/cancellation.
    pressed: boolean;
    // Clear a pending hold and reset pressed state.
    cancel: () => void;
    // Pointer, key, and blur handlers. Spread them onto the interactive control.
    handlers: {
      // Start the hold timer for the primary pointer button.
      onPointerDown: (event: PointerEvent<HTMLElement>) => void;
      // Cancel when the pointer moves farther than movementTolerance.
      onPointerMove: (event: PointerEvent<HTMLElement>) => void;
      // Cancel the timer and clear the pressed state when released.
      onPointerUp: () => void;
      // Cancel if the browser interrupts the pointer gesture.
      onPointerCancel: () => void;
      // Cancel when the pointer leaves the control.
      onPointerLeave: () => void;
      // Start the hold timer for Space or Enter; ignore repeated keydown events.
      onKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
      // Cancel when Space or Enter is released.
      onKeyUp: (event: KeyboardEvent<HTMLElement>) => void;
      // Cancel when the control loses focus.
      onBlur: () => void;
    };
  };
```

</details>

## useDoubleClick

**Single click selects; double click opens the envelope**

A document preview distinguishes selecting an item from opening its preview.

**Why this hook helps:** The hook delays single-trigger work long enough to recognize a second trigger, then cancels the pending single action.

**Keep in mind:** Offer a separate Open button. Delayed click handling changes responsiveness and should not gate keyboard access.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useDoubleClick.tsx)

```tsx
'use client';

import { useState } from 'react';
import { useDoubleClick } from 'use-a-hook';

export default function DocumentClicks() {
  const [message, setMessage] = useState('No document selected.');
  const click = useDoubleClick(
    () => setMessage('Opened the quarterly report preview.'),
    () => setMessage('Selected quarterly report.'),
    250,
  );
  return (
    <section>
      <button onClick={() => click()}>
        Quarterly report: click to select, double-click to open
      </button>
      <button onClick={() => setMessage('Opened the quarterly report preview.')}>
        Open report preview
      </button>
      <p role="status">{message}</p>
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Distinguish a double trigger from a delayed single trigger with cancellation.

```ts
export declare function useDoubleClick(
  // The action when a second trigger arrives during the waiting window.
  onDouble: () => void,
  // Optional action when the waiting window ends without a second trigger.
  onSingle?: () => void,
  // The double-trigger waiting window in milliseconds. Defaults to 250.
  delay?: number
):
  // Returns: A stable trigger function. Call it from onClick; a separate normal action should remain available for keyboard users.
  () => void;
```

</details>

## useDrag

**The sticky note leaves its assigned parking spot**

A canvas-style workspace lets a user drag a local note while keeping rendering aligned with browser frames.

**Why this hook helps:** Pointer capture keeps the gesture connected, movement is frame-batched, and cleanup releases capture.

**Keep in mind:** Set touch-action for the drag surface and provide keyboard alternatives. This primitive does not add collision detection or persistence.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useDrag.tsx)

```tsx
'use client';

import { useState } from 'react';
import { useDrag } from 'use-a-hook';

export default function DraggableNote() {
  const drag = useDrag();
  const [keyboardX, setKeyboardX] = useState(0);
  return (
    <section>
      <p>Drag the note, or use the movement buttons.</p>
      <div
        {...drag.handlers}
        style={{
          touchAction: 'none',
          width: 160,
          padding: 12,
          background: '#fff1a8',
          transform: `translate(${drag.x + keyboardX}px, ${drag.y}px)`,
        }}
      >
        Review the launch checklist
      </div>
      <button onClick={() => setKeyboardX((value) => value - 10)}>Move left</button>
      <button onClick={() => setKeyboardX((value) => value + 10)}>Move right</button>
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Pointer-captured dragging with frame-batched coordinates and cleanup.

```ts
import { type PointerEvent } from 'react';

export declare function useDrag(
  // The starting x/y translation in CSS pixels. Defaults to 0,0.
  initial?: {
    // Starting horizontal translation in CSS pixels.
    x: number;
    // Starting vertical translation in CSS pixels.
    y: number;
  }
):
  // Returns: Frame-batched drag translation and handlers for pointer capture.
  {
    // Pointer handlers to spread onto the drag surface. Set touch-action appropriately and offer keyboard alternatives.
    handlers: {
      // Start dragging with the primary button and capture this pointer.
      onPointerDown: (event: PointerEvent<HTMLElement>) => void;
      // Update the translation, batched to the next animation frame.
      onPointerMove: (event: PointerEvent<HTMLElement>) => void;
      // Finish the drag and release pointer capture.
      onPointerUp: (event: PointerEvent<HTMLElement>) => void;
      // Finish if the browser cancels the gesture.
      onPointerCancel: (event: PointerEvent<HTMLElement>) => void;
      // Finish if this element loses control of the pointer.
      onLostPointerCapture: (event: PointerEvent<HTMLElement>) => void;
    };
    // Whether a drag gesture is active in the latest published frame.
    dragging: boolean;
    // Current horizontal translation in CSS pixels.
    x: number;
    // Current vertical translation in CSS pixels.
    y: number;
  };
```

</details>

## useDropZone

**Files land in the inbox, not on the floor**

A knowledge-library form accepts files dragged from the desktop and also offers a standard file picker.

**Why this hook helps:** Nested drag-enter tracking keeps the active state from flickering as the pointer crosses child elements.

**Keep in mind:** Dropping a file does not upload or validate it. Apply file rules and server-side validation before storage.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useDropZone.tsx)

```tsx
'use client';

import { useState, useCallback } from 'react';
import { useDropZone } from 'use-a-hook';

export default function KnowledgeFileDrop() {
  const [names, setNames] = useState<string[]>([]);
  const receive = useCallback(
    (files: readonly File[]) => setNames(files.map((file) => file.name)),
    [],
  );
  const drop = useDropZone(receive);
  return (
    <section>
      <div {...drop.handlers} style={{ border: '2px dashed', padding: 24 }}>
        <p>{drop.dragging ? 'Files are ready to land.' : 'Drop documents here.'}</p>
        <label>
          Or choose files{' '}
          <input
            type="file"
            multiple
            onChange={(event) => receive(Array.from(event.target.files ?? []))}
          />
        </label>
      </div>
      <ul>
        {names.map((name, index) => (
          <li key={`${name}-${index}`}>{name}</li>
        ))}
      </ul>
    </section>
  );
}
```

<details>
<summary>API signature</summary>

File drop handling with nested drag-enter tracking and a disabled state.

```ts
import { type DragEvent } from 'react';

export declare function useDropZone(
  // Called with the dropped File objects. Uploading and validation remain your app responsibilities.
  onFiles: (files: readonly File[]) => void,
  // Whether to ignore file drags and drops. Defaults to false.
  disabled?: boolean
):
  // Returns: A file-drag flag and handlers to spread onto a drop surface.
  {
    // True while a file drag is over the drop zone, including nested children.
    dragging: boolean;
    // Drag-enter, over, leave, and drop handlers. Also offer a normal file input for keyboard access.
    handlers: {
      // Track file drags entering this element or its children.
      onDragEnter: (event: DragEvent<HTMLElement>) => void;
      // Allow file dropping and show the copy cursor.
      onDragOver: (event: DragEvent<HTMLElement>) => void;
      // Clear the drag indicator after the pointer leaves the whole zone.
      onDragLeave: () => void;
      // Read the dropped files and pass them to onFiles.
      onDrop: (event: DragEvent<HTMLElement>) => void;
    };
  };
```

</details>

## useObjectUrl

**A temporary backstage pass for a photo**

An avatar form previews a selected local image before uploading anything.

**Why this hook helps:** A Blob URL lets the browser display the file and is revoked when replaced or when the component unmounts.

**Keep in mind:** Object URLs are temporary browser resources, not permanent asset links. Store an asset ID or server URL after an actual upload.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useObjectUrl.tsx)

```tsx
'use client';

import { useState } from 'react';
import { useObjectUrl } from 'use-a-hook';

export default function LocalAvatarPreview() {
  const [file, setFile] = useState<File | null>(null);
  const url = useObjectUrl(file);
  return (
    <section>
      <label>
        Choose avatar{' '}
        <input
          type="file"
          accept="image/*"
          onChange={(event) => setFile(event.target.files?.[0] ?? null)}
        />
      </label>
      {url && <img src={url} alt="Selected avatar preview" width={120} height={120} />}
      <button onClick={() => setFile(null)}>Clear preview</button>
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Create a temporary Blob URL and revoke it on replacement or unmount.

```ts
export declare function useObjectUrl(
  // The local File or Blob to preview; null/undefined clears the preview.
  blob: Blob | null | undefined
):
  // Returns: A temporary blob URL, or undefined before creation/when cleared. It is revoked on replacement or unmount.
  string | undefined;
```

</details>

## useFileInput

**The attachment desk checks the baggage allowance**

A support form allows a small number of image attachments within a per-file size limit.

**Why this hook helps:** The hook validates count, extension/MIME, and size before replacing the accepted file list.

**Keep in mind:** HTML accept is only a picker hint. Inspect content, permissions, and size again on the server; validation failures preserve the previous accepted selection.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useFileInput.tsx)

```tsx
'use client';

import { useFileInput } from 'use-a-hook';

export default function SupportAttachments() {
  const picker = useFileInput({
    accept: 'image/*',
    maxFiles: 3,
    maxSize: 2 * 1024 * 1024,
  });
  return (
    <section>
      <label>
        Attach up to 3 images, 2 MiB each{' '}
        <input
          type="file"
          ref={picker.ref}
          accept="image/*"
          multiple
          onChange={picker.onChange}
        />
      </label>
      <button onClick={picker.reset}>Clear attachments</button>
      {picker.errors.length > 0 && (
        <ul role="alert">
          {picker.errors.map((error, index) => (
            <li key={index}>{error}</li>
          ))}
        </ul>
      )}
      <ul>
        {picker.files.map((file, index) => (
          <li key={`${file.name}-${index}`}>{file.name}</li>
        ))}
      </ul>
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Headless file picking with extension/MIME, count, and size validation.

```ts
import { type ChangeEvent } from 'react';

export interface FileInputOptions {
  // Comma-separated file extensions or MIME rules, such as .png,image/*; also set the input HTML accept attribute.
  accept?: string;
  // Maximum number of selected files. Omit for no hook-level count limit.
  maxFiles?: number;
  // Maximum bytes per file. Omit for no hook-level size limit; validate again on the server.
  maxSize?: number;
}

export declare function useFileInput(
  // Accepted file types, maximum file count, and a per-file size limit.
  options?: FileInputOptions
):
  // Returns: Input ref, accepted files, validation errors, and picker actions.
  {
    // Attach this ref to your actual input type=file element.
    ref: import("react").RefObject<HTMLInputElement>;
    // The last accepted read-only list of File objects.
    files: readonly File[];
    // Validation messages for the last rejected selection, or an empty list.
    errors: readonly string[];
    // Validate an iterable of files. Returns true on acceptance; invalid input preserves the previous accepted list.
    select: (input: Iterable<File>) => boolean;
    // Pass to the file input change handler to validate its chosen files.
    onChange: (event: ChangeEvent<HTMLInputElement>) => void;
    // Trigger the attached file input click from a user action.
    open: () => void | undefined;
    // Clear accepted files, errors, and the attached input value.
    reset: () => void;
  };
```

</details>

## useTextSelection

**A highlighter asks, “Did you mean this bit?”**

A document review panel displays the text selected inside its article so a comment can target that excerpt.

**Why this hook helps:** Selection changes are sampled by animation frame and can be scoped to an element, with range bounds available for positioning.

**Keep in mind:** This is a live selection snapshot, not a durable document anchor. Store stable document offsets or IDs for comments that must survive edits.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useTextSelection.tsx)

```tsx
'use client';

import { useState } from 'react';
import { useTextSelection } from 'use-a-hook';

export default function ReviewExcerpt() {
  const [article, setArticle] = useState<HTMLElement | null>(null);
  const selection = useTextSelection(article);
  return (
    <section>
      <article ref={setArticle}>
        <h2>Project brief</h2>
        <p>
          Select part of this paragraph to prepare an excerpt for a review comment. The
          editor keeps the actual document intact.
        </p>
      </article>
      <p role="status">
        {selection.text
          ? `Selected excerpt: “${selection.text}”`
          : 'Select text inside the article.'}
      </p>
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Frame-batched selected text and range bounds, optionally scoped to an element.

```ts
export declare function useTextSelection(
  // Optional element limiting selection to its subtree. Omit for the document; null disables tracking.
  target?: HTMLElement | null
):
  // Returns: The latest selected text and optional range bounds, updated by animation frame.
  {
    // Selected text; empty when selection is collapsed or outside the target.
    text: string;
    // The selection range bounding rectangle, or null when absent/unavailable. It is a live snapshot, not a durable document anchor.
    rect: DOMRect | null;
  };
```

</details>

## useComposedRef

**One element, several interested coworkers**

A chart needs its own DOM ref while a measurement hook and parent component need the same element.

**Why this hook helps:** A composed callback forwards attachment and detachment to each distinct ref, including cleanup-returning callbacks.

**Keep in mind:** Keep the number of ref slots fixed; pass null for an unused slot. Changing a constituent ref makes React detach and reattach it.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useComposedRef.tsx)

```tsx
'use client';
import { useRef } from 'react';
import { useComposedRef, useResizeObserver } from 'use-a-hook';
export default function SharedChartRef() {
  const ownRef = useRef<HTMLDivElement>(null);
  const size = useResizeObserver<HTMLDivElement>();
  const ref = useComposedRef<HTMLDivElement>(ownRef, size.ref);
  return (
    <section>
      <div
        ref={ref}
        style={{ resize: 'horizontal', overflow: 'auto', width: 280 }}
      >
        Resize me. Both refs get the memo.
      </div>
      <p>Chart width: {size.width ?? 'measuring…'}</p>
      <button onClick={() => ownRef.current?.focus()}>Focus chart</button>
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Compose object and callback refs with detach and React 19 cleanup support.

```ts
import { type Ref } from 'react';

export type ComposableRef<T> = Ref<T> | undefined;

export declare function useComposedRef<
  // The type of the referenced value, usually an HTML element.
  T
>(
  // Object refs, callback refs, null, or undefined. Duplicate refs are assigned once.
  ...refs: readonly ComposableRef<T>[]
):
  // Returns: A callback ref that attaches all provided refs and clears them on detachment.
  (node: T | null) => void;
```

</details>

## useViewportSize

**The keyboard ate half the chat window**

A mobile chat composer needs to stay within the visible viewport when the on-screen keyboard opens.

**Why this hook helps:** Visual viewport resize/scroll events publish dimensions and offsets at most once per frame; consumers share subscriptions.

**Keep in mind:** Falls back to layout dimensions when VisualViewport is unavailable. Supply deterministic initial dimensions for SSR.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useViewportSize.tsx)

```tsx
'use client';
import { useViewportSize } from 'use-a-hook';
export default function MobileComposer() {
  const { height, offsetTop } = useViewportSize({ initialHeight: 600 });
  return (
    <section
      style={{
        height,
        transform: `translateY(${offsetTop}px)`,
        display: 'flex',
        flexDirection: 'column'
      }}
    >
      <p style={{ flex: 1 }}>
        The visible viewport is {height ?? '…'} CSS pixels tall. The keyboard
        gets its own seat.
      </p>
      <label>
        Message <input placeholder="Open the mobile keyboard" />
      </label>
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Shared visual viewport dimensions, offsets, and scale with SSR fallbacks.

```ts
import { type ViewportOptions } from './internal/viewport.js';

export type { ViewportOptions } from './internal/viewport.js';

export declare function useViewportSize(
  // Optional initialWidth, initialHeight, and enabled controls.
  options?: ViewportOptions
):
  // Returns: A cached snapshot of visible dimensions, offsets, and zoom scale.
  import("./internal/viewport.js").ViewportSnapshot;
```

</details>

## useDevicePixelRatio

**Crisp charts on the fancy monitor**

A dashboard canvas should repaint sharply when a user moves the window between monitors.

**Why this hook helps:** The hook re-arms a media query for the raw browser ratio, even when the returned number is capped or rounded.

**Keep in mind:** DPR is not CSS pixel size. Multiply canvas backing dimensions by the ratio and retain CSS dimensions.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useDevicePixelRatio.tsx)

```tsx
'use client';
import { useEffect, useRef } from 'react';
import { useDevicePixelRatio } from 'use-a-hook';
export default function CrispCanvas() {
  const ratio = useDevicePixelRatio({ max: 3 });
  const ref = useRef<HTMLCanvasElement>(null);
  useEffect(() => {
    const canvas = ref.current;
    if (!canvas) return;
    canvas.width = Math.round(300 * ratio);
    canvas.height = Math.round(100 * ratio);
    const context = canvas.getContext('2d');
    if (!context) return;
    context.scale(ratio, ratio);
    context.font = '20px sans-serif';
    context.fillText('Crisp on this monitor!', 12, 50);
  }, [ratio]);
  return (
    <figure>
      <canvas
        ref={ref}
        style={{ width: 300, height: 100 }}
        aria-label="Crisp text demonstration"
      />
      <figcaption>Backing scale: {ratio}×</figcaption>
    </figure>
  );
}
```

<details>
<summary>API signature</summary>

Observe raw display pixel ratio changes without polling.

```ts
export interface DevicePixelRatioOptions {
  // Server fallback ratio. Defaults to 1.
  defaultValue?: number;
  // Optional maximum returned ratio. Defaults to no cap.
  max?: number;
  // Round to the nearest integer before capping. Defaults to false.
  round?: boolean;
}

export declare function useDevicePixelRatio(
  // Optional deterministic server value, output cap, and rounding.
  options?: DevicePixelRatioOptions
):
  // Returns: The current device pixel ratio, optionally rounded and capped.
  number;
```

</details>

## useStickToBottom

**The chat scroll respects your lunch break**

Messages stream into a support chat while an agent scrolls upward to read an older answer.

**Why this hook helps:** Content observation schedules scrolling only while following is active. Upward scrolling pauses following until the user returns to the bottom or presses a resume button.

**Keep in mind:** Attach both refs to a normal top-to-bottom overflow container and its content wrapper. Spring physics and column-reverse layouts are outside this API.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useStickToBottom.tsx)

```tsx
'use client';
import { useState } from 'react';
import { useStickToBottom } from 'use-a-hook';
export default function PoliteChatScroll() {
  const [messages, setMessages] = useState([
    'Welcome to support. The scroll respects your boundaries.'
  ]);
  const chat = useStickToBottom();
  return (
    <section>
      <div
        ref={chat.scrollRef}
        tabIndex={0}
        aria-label="Conversation"
        style={{ height: 180, overflowY: 'auto' }}
      >
        <div ref={chat.contentRef}>
          {messages.map((message, index) => (
            <p key={index}>{message}</p>
          ))}
        </div>
      </div>
      <button
        onClick={() =>
          setMessages((items) => [
            ...items,
            `Message ${items.length + 1}: the plot thickens.`
          ])
        }
      >
        Add message
      </button>
      {!chat.isFollowing && (
        <button onClick={() => chat.scrollToBottom()}>Back to latest</button>
      )}
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Event-driven bottom following that respects user scroll-away intent.

```ts
export interface StickToBottomOptions {
  // Start following after mount. Defaults to true; captured for the initial state.
  initial?: boolean;
  // Install automatic scrolling/listeners when true (default).
  enabled?: boolean;
  // Distance from the bottom considered at-bottom, in CSS pixels. Defaults to 4.
  threshold?: number;
  // auto by default; smooth uses native scrolling and respects reduced-motion preferences.
  behavior?: ScrollBehavior;
}

export declare function useStickToBottom(
  // Optional initial following, enablement, threshold, and native scroll behavior.
  options?: StickToBottomOptions
):
  // Returns: Container/content refs, bottom/following state, and explicit resume/stop actions.
  {
    // Attach to the overflow scrolling container.
    scrollRef: import("react").Dispatch<import("react").SetStateAction<HTMLElement | null>>;
    // Attach to the inner content wrapper that grows as messages arrive.
    contentRef: import("react").Dispatch<import("react").SetStateAction<HTMLElement | null>>;
    // Resume following and schedule a scroll; accepts an optional native behavior.
    scrollToBottom: (behavior?: ScrollBehavior | undefined) => void;
    // Stop following and cancel the pending animation frame.
    stopScroll: () => void;
    // Whether the container is within threshold of its bottom.
    isAtBottom: boolean;
    // Whether incoming content may automatically move the scroll position.
    isFollowing: boolean;
  };
```

</details>

## useInfiniteLoader

**The rows arrive before the scrolling party**

A SaaS audit-log grid has a million server-side rows but only renders a small visible window.

**Why this hook helps:** The hook scans the visible window plus a threshold, loads contiguous missing batches one at a time, and remembers completed ranges until reset.

**Keep in mind:** Row bounds are zero-based and inclusive. Keep data in your app, honor AbortSignal, and change resetKey when filters or the dataset change. The demo needs /api/audit-rows to return { index, label }[] for each inclusive batch.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useInfiniteLoader.tsx)

```tsx
'use client';
import { useEffect, useState } from 'react';
import { useInfiniteLoader, useVirtualList } from 'use-a-hook';
export default function AuditLogWindow() {
  const [ids] = useState(() =>
    Array.from({ length: 1000 }, (_, index) => index)
  );
  const [rows, setRows] = useState<ReadonlyMap<number, string>>(new Map());
  const [scrollTop, setScrollTop] = useState(0);
  const visible = useVirtualList(ids, {
    itemHeight: 32,
    viewportHeight: 240,
    scrollTop
  });
  const loader = useInfiniteLoader({
    rowCount: ids.length,
    isRowLoaded: (index) => rows.has(index),
    loadMoreRows: async (start, stop, signal) => {
      const response = await fetch(
        `/api/audit-rows?start=${start}&stop=${stop}`,
        { signal }
      );
      if (!response.ok) throw new Error('The audit-log courier got lost.');
      const data = (await response.json()) as {
        index: number;
        label: string;
      }[];
      if (signal.aborted) return;
      setRows(
        (previous) =>
          new Map([
            ...previous,
            ...data.map((row) => [row.index, row.label] as const)
          ])
      );
    }
  });
  useEffect(() => {
    if (visible.end > visible.start)
      loader.onRowsRendered({
        startIndex: visible.start,
        stopIndex: visible.end - 1
      });
  }, [visible.start, visible.end, loader.onRowsRendered]);
  return (
    <section>
      <div
        onScroll={(event) => setScrollTop(event.currentTarget.scrollTop)}
        style={{ height: 240, overflowY: 'auto' }}
      >
        <div style={{ height: visible.totalHeight, position: 'relative' }}>
          {visible.items.map((row) => (
            <div
              key={row.index}
              style={{ position: 'absolute', top: row.offset, height: 32 }}
            >
              {rows.get(row.index) ?? 'Loading audit row…'}
            </div>
          ))}
        </div>
      </div>
      {loader.loading && <p>Fetching the next chapter…</p>}
      {loader.error !== undefined && (
        <button onClick={loader.retry}>Retry loading</button>
      )}
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Batched virtual-list range loading with deduplication, retries, and cancellation.

```ts
export interface RenderedRange {
  // First visible row, zero-based and inclusive.
  startIndex: number;
  // Last visible row, zero-based and inclusive.
  stopIndex: number;
}

export interface InfiniteLoaderOptions {
  // Total number of rows, finite and nonnegative.
  rowCount: number;
  // Return true for an already available row.
  isRowLoaded: (index: number) => boolean;
  // Load the inclusive row range. Honor the supplied AbortSignal; resolve only when that batch has been handled.
  loadMoreRows: (startIndex: number, stopIndex: number, signal: AbortSignal) => Promise<unknown>;
  // Minimum contiguous batch where available. Defaults to 10.
  minimumBatchSize?: number;
  // Rows of prefetch around the visible window. Defaults to 15.
  threshold?: number;
  // Allow automatic requests. Defaults to true; false aborts the active request.
  enabled?: boolean;
  // Change this when filters/dataset change to abort stale work and clear completed ranges.
  resetKey?: unknown;
}

export declare function useInfiniteLoader(
  // Required row count, loaded-row predicate, and async range loader; optional batch and prefetch controls.
  options: InfiniteLoaderOptions
):
  // Returns: A stable range callback and loading, error, retry, and reset controls.
  {
    // Pass the visible inclusive range; overlapping notifications do not duplicate requests.
    onRowsRendered: (visible: RenderedRange) => void;
    // Abort the current request, clear cached ranges/errors, and reload the current window.
    reset: () => void;
    // Retry the current visible window after a failure.
    retry: () => void;
    // Whether a batch request is active.
    loading: boolean;
    // The last failed request; loading pauses until retry or reset.
    error: unknown;
  };
```

</details>

## useStopwatch

**The meeting has entered its overtime era**

A support agent tracks time spent on a ticket without counting background-tab ticks.

**Why this hook helps:** Elapsed time comes from timestamps plus saved elapsed time; resolution only controls how often the UI refreshes.

**Keep in mind:** autoStart and initialElapsed configure the initial lifecycle. Reset explicitly for another ticket. Accuracy follows the system clock.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useStopwatch.tsx)

```tsx
'use client';
import { useStopwatch } from 'use-a-hook';
export default function TicketStopwatch() {
  const watch = useStopwatch({ resolution: 100 });
  return (
    <section>
      <p>
        {watch.minutes}m {watch.seconds}s spent rescuing this ticket.
      </p>
      <button onClick={watch.start} disabled={watch.isRunning}>
        Start/resume
      </button>
      <button onClick={watch.pause}>Pause</button>
      <button onClick={() => watch.reset()}>New ticket</button>
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Timestamp-based stopwatch with start, pause, and reset controls.

```ts
export interface StopwatchOptions {
  // Start after mounting. Defaults to false.
  autoStart?: boolean;
  // UI update interval in milliseconds, clamped to at least 1. Defaults to 1000.
  resolution?: number;
  // Initial elapsed milliseconds, captured once. Defaults to 0.
  initialElapsed?: number;
}

export declare function useStopwatch(
  // Optional auto-start, update resolution, and initial elapsed milliseconds.
  options?: StopwatchOptions
):
  // Returns: Elapsed time, display components, running state, and stable controls.
  {
    // Start or resume without discarding elapsed time.
    start: () => void;
    // Capture exact current elapsed time and stop repeated updates.
    pause: () => void;
    // Set elapsed milliseconds (default 0); second argument optionally starts it.
    reset: (elapsed?: number | undefined, autoStart?: boolean | undefined) => void;
    // Whole seconds in the sampled duration.
    totalSeconds: number;
    // Whole days.
    days: number;
    // Hour component within the current day.
    hours: number;
    // Minute component within the current hour.
    minutes: number;
    // Second component within the current minute.
    seconds: number;
    // Millisecond component within the current second.
    milliseconds: number;
    // Total sampled elapsed milliseconds.
    elapsed: number;
    // Whether the timer is actively advancing.
    isRunning: boolean;
  };
```

</details>

## useTimer

**The trial countdown needs a pause button**

A timed review task needs pause/resume controls and one expiry notification per run.

**Why this hook helps:** Remaining time is calculated from timestamps, so delayed interval callbacks do not accumulate drift.

**Keep in mind:** initialDuration is captured for the current run; changing it alone does not restart. Use restart for a new run. Use useCountdown for an absolute server deadline.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useTimer.tsx)

```tsx
'use client';
import { useState } from 'react';
import { useTimer } from 'use-a-hook';
export default function ReviewTimer() {
  const [message, setMessage] = useState('The review clock is ready.');
  const timer = useTimer(60_000, {
    autoStart: false,
    resolution: 100,
    onExpire: () => setMessage('Time! The imaginary referee has spoken.')
  });
  return (
    <section>
      <p>
        {timer.minutes}:{String(timer.seconds).padStart(2, '0')}
      </p>
      <p role="status">{message}</p>
      <button onClick={timer.resume}>Start/resume</button>
      <button onClick={timer.pause}>Pause</button>
      <button
        onClick={() => {
          setMessage('Fresh review, fresh clock.');
          timer.restart();
        }}
      >
        Restart
      </button>
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Pausable duration countdown with once-per-run expiry notification.

```ts
export interface TimerOptions {
  // Start after mount. Defaults to true.
  autoStart?: boolean;
  // UI sampling interval in milliseconds, clamped to at least 1. Defaults to 1000.
  resolution?: number;
  // Called once when a running generation expires; always uses the latest committed callback.
  onExpire?: () => void;
}

export declare function useTimer(
  // Nonnegative finite duration in milliseconds.
  initialDuration: number,
  // Optional auto-start, update resolution, and expiry callback.
  options?: TimerOptions
):
  // Returns: Remaining time, display components, running/expiry state, and stable controls.
  {
    // Whether remaining time is zero.
    expired: boolean;
    // Start or resume the paused run; the same behavior as resume.
    start: () => void;
    // Continue from the saved remaining time.
    resume: () => void;
    // Freeze the exact current remaining time.
    pause: () => void;
    // Start a new run with optional duration and autoStart arguments; resets expiry notification.
    restart: (nextDuration?: number | undefined, autoStart?: boolean | undefined) => void;
    // Whole seconds in the sampled duration.
    totalSeconds: number;
    // Whole days.
    days: number;
    // Hour component within the current day.
    hours: number;
    // Minute component within the current hour.
    minutes: number;
    // Second component within the current minute.
    seconds: number;
    // Millisecond component within the current second.
    milliseconds: number;
    // Total sampled remaining milliseconds.
    remaining: number;
    // Whether the timer is actively advancing.
    isRunning: boolean;
  };
```

</details>

## useElapsedTime

**The tiny launch clock**

A product tour has a progress bar. Pausing the tour should pause its clock too; the bar has earned a coffee break.

**Why this hook helps:** A frame loop counts active time and stops after completion. updateInterval limits React publications while the clock keeps accurate frame deltas.

**Keep in mind:** Times are milliseconds. Background tabs follow browser animation scheduling. reset clears the clock; call resume to restart a completed run. Changing duration does not automatically reset it.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useElapsedTime.tsx)

```tsx
import { useElapsedTime } from 'use-a-hook';
export default function TourClock() {
  const clock = useElapsedTime({ duration: 5000, updateInterval: 50 });
  return (
    <section>
      <progress value={clock.elapsed} max={5000} />
      <p>Tour clock: {(clock.elapsed / 1000).toFixed(1)}s</p>
      <button onClick={clock.pause}>Coffee break</button>
      <button onClick={clock.resume}>Continue</button>
      <button
        onClick={() => {
          clock.reset();
          clock.resume();
        }}
      >
        Replay tour
      </button>
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Track active animation time in milliseconds with pausing, bounded duration, and throttled display updates.

```ts
export interface ElapsedTimeOptions {
  // External gate; false suspends frames. Defaults to true.
  playing?: boolean;
  // Maximum active milliseconds; defaults to Infinity.
  duration?: number;
  // Minimum milliseconds between React updates; defaults to 0 (every frame).
  updateInterval?: number;
  // Called once per completed run.
  onComplete?: () => void;
}

export declare function useElapsedTime(
  // Optional playing gate, duration in milliseconds, display update interval, and completion callback.
  { playing, duration, updateInterval, onComplete }?: ElapsedTimeOptions
):
  // Returns: The current values and controls described below.
  {
    // Active elapsed milliseconds, capped at duration.
    elapsed: number;
    // Whether both the playing gate and the local run control allow frames.
    running: boolean;
    // Stop scheduling frames.
    pause: () => void;
    // Resume unless complete; reset a completed run first.
    resume: () => void;
    // Clear elapsed time and completion without automatically resuming.
    reset: () => void;
  };
```

</details>

## useCountUp

**Revenue makes an entrance**

A dashboard celebrates a milestone by counting to the new total. The number gets a red carpet, not a permanent animation loop.

**Why this hook helps:** Interpolation reuses the elapsed-time clock and reaches the exact endpoint, even when easing has rounding error.

**Keep in mind:** Format the number with Intl.NumberFormat. Call reset then resume to replay. Endpoints are live inputs; this does not automatically restart when they change.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useCountUp.tsx)

```tsx
import { useCountUp, useReducedMotion } from 'use-a-hook';
export default function Milestone() {
  const reduced = useReducedMotion();
  const count = useCountUp(2500, { duration: reduced ? 0 : 1200 });
  return (
    <section>
      <p>
        Celebrating {Math.round(count.value).toLocaleString('en-US')} shipped
        projects!
      </p>
      <button
        onClick={() => {
          count.reset();
          count.resume();
        }}
      >
        Encore
      </button>
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Interpolate a numeric metric using a pausable frame clock.

```ts
export interface CountUpOptions {
  // Starting value; defaults to 0.
  from?: number;
  // Animation length in milliseconds; defaults to 1000.
  duration?: number;
  // External run gate; defaults to true.
  playing?: boolean;
  // Map progress from 0 to 1 to an eased progress. Defaults to linear.
  easing?: (progress: number) => number;
  // Called once when the animation completes.
  onComplete?: () => void;
}

export declare function useCountUp(
  // Final numeric value.
  to: number,
  // Optional starting value, duration in milliseconds, playing gate, easing, and completion callback.
  { from, duration, playing, easing, onComplete }?: CountUpOptions
):
  // Returns: The current values and controls described below.
  {
    // Interpolated number; exact to value when complete.
    value: number;
    // Elapsed active milliseconds.
    elapsed: number;
    // Whether frames are enabled.
    running: boolean;
    // Pause the animation.
    pause: () => void;
    // Resume an incomplete run.
    resume: () => void;
    // Clear the clock; call resume after a completed run.
    reset: () => void;
  };
```

</details>

## useContainerQuery

**The card chooses its outfit**

A billing card appears in both a narrow sidebar and a wide dashboard. It dresses for its container, not the whole browser.

**Why this hook helps:** Shared, frame-batched ResizeObserver measurements only update React when a named condition changes.

**Keep in mind:** Prefer CSS container queries for styling alone. Use this hook when size changes actual rendering or behavior. Bounds are inclusive; missing measurements match no rules.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useContainerQuery.tsx)

```tsx
import { useContainerQuery } from 'use-a-hook';
export default function BillingCard() {
  const { ref, matches } = useContainerQuery({ roomy: { minWidth: 480 } });
  return (
    <section
      ref={ref}
      style={{
        resize: 'horizontal',
        overflow: 'auto',
        minWidth: 200,
        padding: 16,
        border: '1px solid'
      }}
    >
      <h2>Team billing</h2>
      {matches.roomy ? (
        <p>Room for the whole invoice parade: plan, seats, renewal date.</p>
      ) : (
        <p>Compact crew: $29/month.</p>
      )}
      <small>Drag the container edge to change its outfit.</small>
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Evaluate named size rules with renders only when breakpoint matches change.

```ts
import { type ElementSize } from './useResizeObserver.js';

export interface ContainerCondition {
  // Minimum width, inclusive, in CSS pixels.
  minWidth?: number;
  // Maximum width, inclusive, in CSS pixels.
  maxWidth?: number;
  // Minimum height, inclusive, in CSS pixels.
  minHeight?: number;
  // Maximum height, inclusive, in CSS pixels.
  maxHeight?: number;
}

export declare function useContainerQuery<
  // The rule names, inferred from your object keys.
  K extends string,
  // The measured element type; defaults to HTMLElement.
  T extends Element = HTMLElement
>(
  // Object of named, inclusive width/height constraints.
  queries: Record<K, ContainerCondition>,
  // Optional deterministic server/initial size; omitted means no initial matches.
  initialSize?: ElementSize
):
  // Returns: The current values and controls described below.
  {
    // Attach this callback ref to the container to observe.
    ref: import("react").Dispatch<import("react").SetStateAction<T | null>>;
    // Boolean result for each rule name; unchanged matches preserve identity.
    matches: Record<K, boolean>;
  };
```

</details>

## usePortal

**The tooltip escapes the clipping dungeon**

A dashboard tooltip needs to escape an overflow-hidden panel. A portal gives it a doorway into the document body.

**Why this hook helps:** The hook creates and cleans up only its own host. React DOM stays in your application so the library keeps React as its only runtime dependency.

**Keep in mind:** Call createPortal from react-dom in your component. The host is null during SSR and before effects. Dialog focus, keyboard behavior, and ARIA remain application responsibilities.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/usePortal.tsx)

```tsx
import { useState } from 'react';
import { createPortal } from 'react-dom';
import { usePortal } from 'use-a-hook';
export default function PortalNotice() {
  const [open, setOpen] = useState(false);
  const host = usePortal({ enabled: open });
  return (
    <>
      <button onClick={() => setOpen((value) => !value)}>
        Toggle floating notice
      </button>
      {host &&
        createPortal(
          <aside
            style={{
              position: 'fixed',
              bottom: 16,
              right: 16,
              padding: 16,
              background: 'white',
              color: 'black',
              border: '1px solid'
            }}
          >
            I escaped the clipping dungeon!{' '}
            <button onClick={() => setOpen(false)}>Dismiss</button>
          </aside>,
          host
        )}
    </>
  );
}
```

<details>
<summary>API signature</summary>

Own an SSR-safe DOM host for rendering portal content.

```ts
export interface PortalOptions {
  // Create the host when true; defaults to true.
  enabled?: boolean;
  // Optional parent element; defaults to document.body.
  target?: HTMLElement | null;
  // Optional ID assigned to the newly created host; it never adopts existing nodes.
  id?: string;
}

export declare function usePortal(
  // Optional enablement, parent element, and host ID.
  { enabled, target, id }?: PortalOptions
):
  // Returns: A portal host element, or null before mounting or while disabled.
  HTMLElement | null;
```

</details>

## useScreenshot

**The support ticket gets a picture**

A support panel attaches an image of a chart. A picture is worth a thousand “it looked weird” messages.

**Why this hook helps:** Capture state, errors, cancellation, and competing requests stay in one hook. Your chosen renderer is loaded only by applications that need it.

**Keep in mind:** This hook does not render arbitrary HTML itself. Supply a renderer, such as a canvas exporter or a separately installed DOM capture library. Honor AbortSignal when possible; obsolete results are ignored either way.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useScreenshot.tsx)

```tsx
import { useEffect } from 'react';
import { useScreenshot } from 'use-a-hook';
export default function ChartSnapshot() {
  // This working example captures a canvas. For arbitrary HTML, inject your own renderer.
  const snapshot = useScreenshot<HTMLCanvasElement>((canvas) =>
    canvas.toDataURL('image/png')
  );
  useEffect(() => {
    const context = snapshot.ref.current?.getContext('2d');
    if (!context) return;
    context.fillStyle = '#17324d';
    context.fillRect(0, 0, 320, 120);
    context.fillStyle = '#7fffd4';
    context.fillRect(20, 60, 70, 40);
    context.fillRect(120, 35, 70, 65);
    context.fillRect(220, 10, 70, 90);
  }, [snapshot.ref]);
  return (
    <section>
      <canvas
        ref={snapshot.ref}
        width={320}
        height={120}
        aria-label="Three rising preview bars"
      />
      <button
        disabled={snapshot.capturing}
        onClick={() => void snapshot.capture()}
      >
        Picture, please
      </button>
      {snapshot.error !== undefined && (
        <p role="alert">Capture failed. Try again.</p>
      )}
      {snapshot.image && (
        <a download="chart.png" href={snapshot.image}>
          Download chart
        </a>
      )}
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Capture an element through an injected renderer with cancellation and stale-result protection.

```ts
export declare function useScreenshot<
  // HTML element type held by the target ref.
  T extends HTMLElement
>(
  // Render the target to an image URL or data URL. Receives an AbortSignal; may return a promise.
  render: (element: T, signal: AbortSignal) => string | Promise<string>
):
  // Returns: The current values and controls described below.
  {
    // Start a capture; resolves to the image, or null on failure, missing target, or supersession.
    capture: () => Promise<string | null>;
    // Abort pending work and clear the image and error.
    reset: () => void;
    // Last successful image URL, or null.
    image: string | null;
    // Latest capture error, or undefined.
    error: unknown;
    // Whether the current capture is pending.
    capturing: boolean;
    // Attach to the element to capture.
    ref: import("react").MutableRefObject<T | null>;
  };
```

</details>

## useErrorBoundary

**The widget has a safety net**

One report widget crashes while rendering. The rest of the dashboard should keep its meeting with reality.

**Why this hook helps:** A stable class boundary catches descendant render errors. reset retries the subtree; showBoundary routes a caught event or async failure into the same fallback.

**Keep in mind:** Render the returned ErrorBoundary once per hook instance. React boundaries do not catch SSR failures, their own fallback errors, event handlers, or promises automatically. Catch async errors and call showBoundary explicitly.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useErrorBoundary.tsx)

```tsx
import { useErrorBoundary } from 'use-a-hook';
function ReportWidget() {
  return <p>The report widget is doing fine today.</p>;
}
export default function ResilientReport() {
  const { ErrorBoundary, showBoundary } = useErrorBoundary();
  return (
    <ErrorBoundary
      fallback={(_error, reset) => (
        <p role="alert">
          The widget tripped. <button onClick={reset}>Try again</button>
        </p>
      )}
    >
      <ReportWidget />
      <button
        onClick={() =>
          showBoundary(new Error('A deliberately simulated widget failure'))
        }
      >
        Try the safety net
      </button>
    </ErrorBoundary>
  );
}
```

<details>
<summary>API signature</summary>

Catch descendant render failures with a stable boundary component and explicit recovery.

```ts
import { type ReactNode, type ComponentType, type ErrorInfo } from 'react';

export interface HookBoundaryProps {
  // Descendant UI protected by the boundary.
  children?: ReactNode;
  // Content or a function returning recovery UI.
  fallback?: ReactNode | ((error: unknown, reset: () => void) => ReactNode);
}

export declare function useErrorBoundary(
  // Optional reporting callback receiving React error information.
  onError?: (error: Error, info: ErrorInfo) => void
):
  // Returns: The current values and controls described below.
  {
    // Clear the failure and retry rendering children.
    reset: () => void;
    // Explicitly display a caught event or async error in the mounted boundary.
    showBoundary: (error: unknown) => void;
    // Most recent captured error, which may be any thrown value.
    error: unknown;
    // Whether the boundary currently reports a failure.
    didCatch: boolean;
    // Stable component wrapping the subtree. Accepts children and fallback content or a function of error and reset.
    ErrorBoundary: ComponentType<HookBoundaryProps>;
  };
```

</details>

## useCookie

**The welcome banner remembers**

A welcome banner remembers that a teammate has already taken the tour. The cookie saves everyone another confetti avalanche.

**Why this hook helps:** Subscribers refresh together after writes, on focus, on visibility, and on Cookie Store events where supported. There is no polling timer.

**Keep in mind:** Only JavaScript-readable cookies are available; HttpOnly cookies are server-managed. Delete using the same path/domain. Without Cookie Store support, external writes refresh on focus/visibility or refresh(). Cookie policies may reject writes; check the returned boolean.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/useCookie.tsx)

```tsx
import { useCookie } from 'use-a-hook';
export default function WelcomeTour() {
  const tour = useCookie('tour-completed', {
    maxAge: 60 * 60 * 24 * 30,
    sameSite: 'Lax'
  });
  return (
    <section>
      {tour.value === 'yes' ? (
        <p>Welcome back, confetti veteran.</p>
      ) : (
        <>
          <p>Take the tiny product tour!</p>
          <button
            onClick={() => {
              if (!tour.set('yes'))
                window.alert('Your browser did not store the preference.');
            }}
          >
            Tour complete
          </button>
        </>
      )}
      <button onClick={() => tour.remove()}>Show tour again</button>
    </section>
  );
}
```

<details>
<summary>API signature</summary>

Read and write browser-accessible cookies with same-document synchronization and lifecycle refresh.

```ts
export interface CookieOptions {
  // Cookie path; defaults to /.
  path?: string;
  // Optional domain; omitted means the current host.
  domain?: string;
  // Lifetime in seconds; nonpositive values expire the cookie.
  maxAge?: number;
  // Optional absolute expiration Date.
  expires?: Date;
  // Strict, Lax (default), or None.
  sameSite?: 'Strict' | 'Lax' | 'None';
  // Limit transmission to HTTPS when true; defaults to false.
  secure?: boolean;
}

export declare function useCookie(
  // Cookie name; encoded before reading or writing.
  name: string,
  // Cookie scope, lifetime, and browser attributes. Changing options affects future writes.
  options?: CookieOptions
):
  // Returns: The current values and controls described below.
  {
    // Current readable value, or undefined; initially undefined for hydration.
    value: string | undefined;
    // Write an encoded string; returns whether the matching readable value was observed.
    set: (value: string) => boolean;
    // Expire the cookie using the configured scope; returns whether it is absent.
    remove: () => boolean;
    // Reread browser cookies now.
    refresh: () => void;
  };
```

</details>

## createContextState

**The workspace avoids the rerender conga**

A workspace shares filters and unread counts. Updating the unread badge should not make every filter join the rerender parade.

**Why this hook helps:** A stable store lives inside each Provider. useSelector subscribes only to the selected value and can use an equality function for composite selections.

**Keep in mind:** Create the factory at module scope. Updates must return immutable snapshots. initialValue is read once per Provider; providers never share mutable state, including during SSR.

[Open the complete example](https://unpkg.com/use-a-hook@0.3.2/examples/createContextState.tsx)

```tsx
import { createContextState } from 'use-a-hook';
// Create this once at module scope. Each Provider gets its own store.
const Workspace = createContextState({ unread: 0, filter: 'all' });
function InboxBadge() {
  const unread = Workspace.useSelector((state) => state.unread);
  const update = Workspace.useUpdate();
  return (
    <button
      onClick={() =>
        update((state) => ({ ...state, unread: state.unread + 1 }))
      }
    >
      {unread} unread pigeons
    </button>
  );
}
function Filter() {
  const filter = Workspace.useSelector((state) => state.filter);
  const update = Workspace.useUpdate();
  return (
    <select
      aria-label="Inbox filter"
      value={filter}
      onChange={(event) =>
        update((state) => ({ ...state, filter: event.target.value }))
      }
    >
      <option value="all">All pigeons</option>
      <option value="urgent">Urgent pigeons</option>
    </select>
  );
}
export default function WorkspaceInbox() {
  return (
    <Workspace.Provider>
      <InboxBadge />
      <Filter />
    </Workspace.Provider>
  );
}
```

<details>
<summary>API signature</summary>

Create provider-isolated state with selector subscriptions and stable update actions.

```ts
import { type ReactNode, type SetStateAction } from 'react';

export declare function createContextState<
  // The full state type shared inside each Provider.
  T
>(
  // Default initial state, or a pure initializer called once per Provider mount (Strict Mode may check it twice).
  initial: T | (() => T)
):
  // Returns: The current values and controls described below.
  {
    // Wrap consumers; accepts children and an optional initialValue read only on mount.
    Provider: ({ children, initialValue }: {
        children?: ReactNode;
        initialValue?: T | undefined;
    }) => import("react").FunctionComponentElement<import("react").ProviderProps<{
        snapshot: () => T;
        serverSnapshot: () => T;
        subscribe: (listener: () => void) => () => void;
        set: (next: SetStateAction<T>) => void;
    } | null>>;
    // Select state with optional equality; called as a hook inside the Provider.
    useSelector: <S>(selector: (value: T) => S, equal?: (left: S, right: S) => boolean) => S;
    // Read the stable React-style setter without subscribing to state.
    useUpdate: () => (next: SetStateAction<T>) => void;
  };
```

</details>

The same reference ships as [API.md](https://unpkg.com/use-a-hook@0.3.2/API.md). It is generated from the catalog, typed examples, and build declarations, then included here so it can appear on the npm package page too.

## Contributing

A useful contribution starts with a concrete problem, a complete example, types, meaningful behavior tests, and an independently importable entry point. Please keep the collection focused; a new name for an existing hook does not need a new export.

```sh
npm ci
npm run check
```

The release checks cover React 18/19 behavior, consumer types, server rendering, cleanup, packed ESM/CommonJS exports, and bundle budgets. Edit `docs/readme-template.md` for this introduction; `npm run build` refreshes the README and full API section together. Edit `catalog.json` and `examples/` for individual hook explanations and demos.

Version **0.3.2** · **MIT license** · [Report an issue](https://github.com/sannminwin/use-a-hook/issues)

{preview}

Workspace activity

Report exported!

Revenue report

Quarterly report preview

Billing overview

Profile

Billing