# @vincent.ri/react-tils

> React hooks for browser state and interaction that render the right first frame: SSR-safe, hydration-correct, tested in real browsers, and documented for AI coding agents.

Install: `npm install @vincent.ri/react-tils`. Every hook renders on the server, hydrates without mismatch, and cleans up after itself.

## Pick a hook

| Task                                                                                   | Use                                                                                                                          |
| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| JS logic depends on viewport size, color scheme, reduced motion, pointer, orientation  | `useMediaQuery(query, serverValue?)`                                                                                         |
| Exact window width/height in pixels (canvas, virtualization, popover placement)        | `useWindowSize(serverValue?)`                                                                                                |
| Show offline state, disable network actions                                            | `useOnline(serverValue?)`                                                                                                    |
| Pause polling/video/timers while the tab is hidden, refresh on return                  | `useDocumentVisibility(serverValue?)`                                                                                        |
| Dark mode / reduced motion in JS                                                       | `useMediaQuery('(prefers-color-scheme: dark)')`                                                                              |
| Keep state for this tab only (form step, dismissed banner this visit)                  | `useSessionStorage(key, serverValue)`                                                                                        |
| Scroll position (back-to-top button, hide header on scroll, progress bar)              | `useWindowScroll(serverValue?)`                                                                                              |
| Is an element on screen (lazy load, infinite list, play when visible)                  | `useInView(options?)`                                                                                                        |
| An element's pixel size (canvas/chart sized to its container)                          | `useElementSize({ box? })`                                                                                                   |
| Only styles depend on an element's size                                                | No hook. Use CSS container queries.                                                                                          |
| The window is visible but the user is in another window (pause, mark as read)          | `useWindowFocus(serverValue?)`                                                                                               |
| Render something only in the browser (local time, client-only widget)                  | `useHydrated()` instead of `useState(false)` + `useEffect`                                                                   |
| User's language for a default locale or `Intl` formatting                              | `usePreferredLanguages(serverValue?)` (pass the parsed `Accept-Language` header as `serverValue`)                            |
| Show the right button for a permission (granted / denied / prompt) without prompting   | `usePermission(name)`                                                                                                        |
| User inactive for a while ("Are you still there?", set status to away)                 | `useIdle(timeoutMs?)`                                                                                                        |
| User's location after they ask for it                                                  | `useGeolocation({ enabled })`; keep `enabled` false until a click                                                            |
| Rough location (country, city)                                                         | No hook. Use IP-based location on the server; no prompt.                                                                     |
| Close a dropdown/popover/menu when the user presses outside it                         | `useClickOutside(handler, enabled?)` on a wrapper around the menu and its button, or native `<dialog>` / `popover`           |
| Close a menu/popover/combobox when focus leaves it (Tab out), or save an inline editor | `useFocusWithin({ onLeave })` → `[ref, focused]`; pair with `useClickOutside` via `useMergedRefs`                            |
| Keyboard shortcut (`mod+k` palette, Escape to close, `/` to search, `g i` sequences)   | `useHotkey(hotkey, handler, options?)`                                                                                       |
| "Copy" button with a "Copied!" label                                                   | `useCopyToClipboard(resetMs?)`                                                                                               |
| Stop the page scrolling behind a modal or drawer                                       | `useScrollLock(locked)`                                                                                                      |
| Warn before leaving with unsaved changes                                               | `useBeforeUnload(when)` (does not catch client-side router navigation)                                                       |
| Any other window/document/element event                                                | `useEventListener(target, type, handler, options?)`                                                                          |
| Polling, countdown, clock, carousel                                                    | `useInterval(callback, delayMs \| null, { pauseWhenHidden? })`                                                               |
| Live updates pushed by the server (notifications, job progress, prices, logs)          | `useEventSource(url, { onMessage?, events?, pauseWhenHidden? })` → `{ status, data }`; not for POST/AI streams               |
| Auto-dismiss a toast, hide "Saved" after 2s, delay before showing a spinner            | `useTimeout(callback, delayMs \| null)` → `restart`                                                                          |
| Reusable component, controlled or uncontrolled (`value` / `defaultValue` / `onChange`) | `useControllableState(value, defaultValue, onChange?)`; never copy a prop into state                                         |
| Floating toolbar for selected text (highlight, quote, "Ask AI about this")             | `useTextSelection()` → `[ref, selection]`                                                                                    |
| Render the current time (clock, countdown, "5 minutes ago")                            | `useNow(intervalMs, serverValue?)`; never `new Date()` in render                                                             |
| Canvas drawing, game loop, per-frame updates                                           | `useAnimationFrame(callback, active?)`; for UI animation use CSS or `element.animate()`                                      |
| Tabs or panels linkable through the URL hash (`/settings#billing`)                     | `useHash(serverValue?)` → `[hash, setHash]`                                                                                  |
| Tabs, search, filters, sort, or page number kept in the URL query (`?tab=billing`)     | `useSearchParam(name, serverValue?)` → `[value, set]`; `set(v, { push: true })` for a Back step; skip if your router has one |
| One element needs several refs (forwarded `ref`, `useInView`, `useElementSize`)        | `useMergedRefs(...refs)`                                                                                                     |
| Third-party SDK from a URL (Stripe.js, Maps, chat widget)                              | `useScript(src, { enabled?, attributes? })`; prefer an npm package with `import()` if one exists                             |
| Keep the screen on (recipe, presentation, directions, ticket QR)                       | `useWakeLock(enabled)`                                                                                                       |
| Fullscreen button for a player, viewer, slideshow, or game                             | `useFullscreen()`                                                                                                            |
| Native "Share" sheet                                                                   | `useShare()`, with `useCopyToClipboard` as the fallback                                                                      |
| Camera or microphone (video preview, QR scan, recording)                               | `useUserMedia(constraints, { enabled? })`; stops tracks on unmount                                                           |
| Take a photo on a phone without a live preview                                         | No hook. `<input type="file" accept="image/*" capture>`                                                                      |
| Tell other tabs about an event (logged out, cart updated)                              | `useBroadcastChannel(name, onMessage?)` → `post`                                                                             |
| Drag-and-drop file upload area                                                         | `useFileDrop(onDrop, { enabled? })` → `[ref, isOver]`; keep an `<input type="file">` too                                     |
| Press-and-hold on touch (select item, preview)                                         | `useLongPress(onLongPress, { delayMs?, moveTolerance? })`; spread onto the element                                           |
| Search-as-you-type, autosave, validate after the user pauses                           | `useDebouncedCallback(fn, delayMs, { maxWaitMs? })`; for expensive rendering use `useDeferredValue`                          |
| Debounced copy of state (a query to fetch with), not a debounced handler               | `useDebouncedValue(value, delayMs)`                                                                                          |
| Run during a burst at most every N ms (live results, send cursor/typing, slider save)  | `useThrottledCallback(fn, intervalMs)`; to run once after the user stops, use `useDebouncedCallback`                         |
| The previous value of a prop or state (price ▲/▼, slide direction, "changed from X")   | `usePrevious(value)`; never a ref read during render                                                                         |
| Scroll position or edges of a scroll container (fade shadows, "read to the end")       | `useElementScroll()` → `[ref, { y, atTop, atBottom, … }]`; for the page use `useWindowScroll`                                |
| Chat, AI chat, or log that follows new messages until the user scrolls up              | `useStickToBottom()` → `[ref, { atBottom, scrollToBottom }]`                                                                 |
| Highlight the current section in a table of contents or docs sidebar                   | `useScrollSpy(ids, { offset? })` → active id                                                                                 |
| Chat input or comment box that grows with its text                                     | `useAutosizeTextarea({ maxRows? })` → `ref`; set the minimum with `rows`                                                     |
| Paste screenshots or files into a chat, editor, or upload area                         | `usePasteFiles(onFiles, { accept? })` → `ref`; pairs with `useFileDrop`                                                      |
| Style a sticky header once it sticks (shadow, border, smaller)                         | `useIsStuck()` → `[ref, stuck]`; the element needs `position: sticky`                                                        |
| Refresh stale data when the user comes back with the Back button                       | `usePageRestore(callback)` (back/forward cache)                                                                              |
| Resizable panel, splitter, custom slider, dragging on a canvas                         | `useDrag(onDrag, { threshold? })` → `ref`; add CSS `touch-action: none`                                                      |
| Spotlight, tooltip, crosshair, or magnifier at the pointer over an element             | `usePointerPosition()` → `[ref, { x, y } \| null]`; page-wide cursor: `useEventListener` + a CSS variable                    |
| Tell screen reader users "Copied", "Added to cart", "3 results"                        | `useAnnounce()` → `announce(message, politeness?)`                                                                           |
| `@mention` or `/command` popup at the caret in a textarea                              | `useCaretPosition()` → `[ref, { top, left, height } \| null]`                                                                |
| Record a voice note, voice input for AI chat, or a video message                       | `useMediaRecorder(stream)` with `useUserMedia`; picks a format the browser supports                                          |
| "Read aloud" button for AI answers or articles                                         | `useSpeechSynthesis()` → `{ voices, speaking, speak, cancel }`                                                               |
| "New version available, reload" banner in a PWA                                        | `useServiceWorkerUpdate({ checkIntervalMs? })`; the worker must handle `SKIP_WAITING`                                        |
| Reading-progress bar for an article                                                    | `useScrollProgress()` → `[ref, progress]` from 0 to 1                                                                        |
| A preference the server must know on the first request (theme, locale, currency)       | `useCookie(name, serverValue)`; pass the request's cookie as `serverValue`                                                   |
| Dictation: speech to text in a search box or chat input                                | `useSpeechRecognition({ lang?, continuous? })`; Chrome, Edge, Safari only                                                    |
| Tilt effects, a compass, steering by tilting the phone                                 | `useDeviceOrientation()`; on iOS call `requestPermission()` from a tap                                                       |
| Arrow-key navigation in a toolbar, menu, tab list, or listbox (one Tab stop)           | `useRovingFocus({ orientation?, loop? })`; radio groups and `<select>` do it natively                                        |
| Hide the header on scroll down, show it on scroll up                                   | `useScrollDirection(threshold?)`                                                                                             |
| Keep keyboard focus inside a custom modal or drawer                                    | `useFocusTrap(active)`; prefer `<dialog>` with `showModal()`                                                                 |
| Swipe between slides, swipe to dismiss                                                 | `useSwipe(onSwipe, { threshold? })`, plus CSS `touch-action`                                                                 |
| Keep a bottom bar or chat input above the mobile keyboard                              | `useVisualViewport()` → `bottomInset`                                                                                        |
| Skip autoplay or prefetch on data saver or slow connections                            | `useNetworkInformation()` (Chromium only; unknown elsewhere)                                                                 |
| Dark mode toggle without a flash of the wrong theme                                    | No hook can do it: the first paint happens before React. Use an inline script in `<head>` (e.g. `next-themes`)               |
| Only styling changes with the viewport                                                 | No hook. Use CSS `@media`.                                                                                                   |
| Persist preferences, drafts, or UI state across reloads and tabs                       | `useLocalStorage(key, serverValue)`                                                                                          |
| Store tokens or personal data                                                          | No hook. Never localStorage; use httpOnly cookies.                                                                           |
| Store large data (over ~1 MB)                                                          | No hook. Use IndexedDB.                                                                                                      |

Import from the root or from the hook's own path. Both tree-shake.

```ts
import { useMediaQuery } from '@vincent.ri/react-tils'
import { useMediaQuery } from '@vincent.ri/react-tils/useMediaQuery'
```

## Coming from another library

Names from react-use, ahooks, usehooks-ts, @uidotdev/usehooks, MUI, and Mantine, and the react-tils hook to use instead. Check the API in its JSDoc: arguments differ.

| Their name                                                        | Use                      |
| ----------------------------------------------------------------- | ------------------------ |
| `useAutoScroll`, `useChatScroll`                                  | `useStickToBottom`       |
| `useActiveSection`, `useScrollspy`                                | `useScrollSpy`           |
| `useTextareaAutosize`, `useAutoResize`, `react-textarea-autosize` | `useAutosizeTextarea`    |
| `usePaste`, `useClipboardFiles`                                   | `usePasteFiles`          |
| `useSticky`, `useStickyFixed`                                     | `useIsStuck`             |
| `useBfcache`, `usePageShow`                                       | `usePageRestore`         |
| `useDraggable`, `useGesture` (`onDrag`), `usePointerDrag`         | `useDrag`                |
| `useAnnouncer`, `useLiveAnnouncer`, `LiveAnnouncer`               | `useAnnounce`            |
| `useCaretCoordinates`, `textarea-caret`                           | `useCaretPosition`       |
| `useRecorder`, `useAudioRecorder`, `react-media-recorder`         | `useMediaRecorder`       |
| `useSpeech`, `useTextToSpeech`, `react-speech-kit`                | `useSpeechSynthesis`     |
| `useRegisterSW`, `useServiceWorker`                               | `useServiceWorkerUpdate` |
| `useReadingProgress`, `useScrollPercentage`                       | `useScrollProgress`      |
| `useCookies` (react-cookie), `useCookieState`                     | `useCookie`              |
| `useSpeechToText`, `react-speech-recognition`, `useVoice`         | `useSpeechRecognition`   |
| `useOrientation` (react-use), `useDeviceMotion`, `useGyroscope`   | `useDeviceOrientation`   |
| `useMouse` (react-use), `useMousePosition`, `usePointer`          | `usePointerPosition`     |
| `useFocusOutside`, `useFocusLeave`                                | `useFocusWithin`         |
| `useSSE`, `useServerSentEvents`                                   | `useEventSource`         |
| `useClickAway`, `useOnClickOutside`                               | `useClickOutside`        |
| `useControlled`, `useUncontrolled`, `useControllableValue`        | `useControllableState`   |
| `useDebounce`, `useDebounceValue`                                 | `useDebouncedValue`      |
| `useDebounceCallback`, `useDebounceFn`                            | `useDebouncedCallback`   |
| `useThrottle`, `useThrottleFn`, `useThrottleCallback`             | `useThrottledCallback`   |
| `useQueryState` (nuqs), `useUrlState`, `useQueryParam`            | `useSearchParam`         |
| `usePreviousDistinct`                                             | `usePrevious`            |
| `useExternal`                                                     | `useScript`              |
| `useIntersection`, `useIntersectionObserver`, `useInViewport`     | `useInView`              |
| `useIsClient`, `useMounted`                                       | `useHydrated`            |
| `useKey`, `useKeyPress`, `useHotkeys`                             | `useHotkey`              |
| `useLocalStorageState`                                            | `useLocalStorage`        |
| `useLockBodyScroll`                                               | `useScrollLock`          |
| `useMeasure`, `useSize`, `useResizeObserver`                      | `useElementSize`         |
| `useMedia`, `useBreakpoint`, `useResponsive`                      | `useMediaQuery`          |
| `useMergeRefs`, `useForkRef`, `mergeRefs`                         | `useMergedRefs`          |
| `useNetworkState`, `useNetwork`                                   | `useOnline`              |
| `usePageVisibility`                                               | `useDocumentVisibility`  |
| `useRafLoop`                                                      | `useAnimationFrame`      |
| `useRovingTabIndex`                                               | `useRovingFocus`         |
| `useScroll`                                                       | `useElementScroll`       |
| `useSessionStorageState`                                          | `useSessionStorage`      |
| `useTimeoutFn`                                                    | `useTimeout`             |

## Do not write these patterns

These are the bugs this library exists to prevent. If you see them in user code, replace them with a hook from the table above.

```tsx
// ❌ Reads window during render: crashes on the server.
const isWide = window.innerWidth > 768

// ❌ Different value on server and client: hydration mismatch.
const [isWide] = useState(() => typeof window !== 'undefined' && window.innerWidth > 768)

// ❌ useEffect + useState for an external store: one wrong frame after
// hydration, and components can disagree during concurrent rendering.
const [isWide, setIsWide] = useState(false)
useEffect(() => {
  const mql = window.matchMedia('(min-width: 768px)')
  setIsWide(mql.matches)
  mql.addEventListener('change', (e) => setIsWide(e.matches))
  // ❌ and no cleanup: leaks a listener on every mount
}, [])

// ❌ "mounted" flag: renders false first on every client-side mount (a flash).
const [mounted, setMounted] = useState(false)
useEffect(() => setMounted(true), [])

// ❌ Prop copied into state: goes stale when the prop changes, or flickers when
// "fixed" with a sync effect. Use useControllableState, or derive during render.
const [open, setOpen] = useState(props.open)
useEffect(() => setOpen(props.open), [props.open])

// ❌ Server and client clocks differ: hydration mismatch.
return <time>{new Date().toLocaleTimeString()}</time>

// ❌ Ref read during render: stale under the React Compiler and concurrent
// rendering, and equal to the current value after any unrelated re-render.
const ref = useRef(value)
useEffect(() => {
  ref.current = value
})
const previous = ref.current

// ❌ Reads the URL during render: crashes on the server, mismatches on hydration.
const tab = new URLSearchParams(location.search).get('tab')

// ✅
const isWide = useMediaQuery('(min-width: 768px)')
const hydrated = useHydrated()
const now = useNow(1000) // null until hydrated
const previous = usePrevious(value)
const [tab, setTab] = useSearchParam('tab', serverTab)
```

# API

## componentMatrix

```ts
import { componentMatrix } from '@vincent.ri/react-tils/testing'
function componentMatrix(Component: FunctionComponent): void
```

Registers vitest tests that prove a component is safe to ship: it renders on
the server without DOM globals, hydrates with no mismatch, and removes every
listener it adds after a StrictMode mount/unmount.

Use it on components that read browser state (viewport, storage, network,
visibility). For a single hook, `hookMatrix` is shorter. Call inside a
`describe` in a test file running in a DOM environment (happy-dom or jsdom).
Requires `vitest` and `react-dom`.

@example
// Sidebar.test.tsx
import { describe } from 'vitest'
import { componentMatrix } from '@vincent.ri/react-tils/testing'
import { Sidebar } from './Sidebar'

describe('Sidebar', () => {
  componentMatrix(Sidebar)
})

## hookMatrix

```ts
import { hookMatrix } from '@vincent.ri/react-tils/testing'
function hookMatrix(useHook: () => unknown): void
```

Registers vitest tests that prove a hook is safe to ship: it renders on the
server without DOM globals, hydrates with no mismatch, and removes every
listener it adds after a StrictMode mount/unmount.

Use it on every custom hook you write, especially hooks that read browser
state. Call inside a `describe` in a test file running in a DOM environment
(happy-dom or jsdom). Requires `vitest` and `react-dom`.

@example
// useScrollY.test.ts
import { describe } from 'vitest'
import { hookMatrix } from '@vincent.ri/react-tils/testing'
import { useScrollY } from './useScrollY'

describe('useScrollY', () => {
  hookMatrix(() => useScrollY())
})

## useAnimationFrame

```ts
import { useAnimationFrame } from '@vincent.ri/react-tils'
function useAnimationFrame(callback: (deltaMs: number, timeMs: number) => void, active?: boolean): void
```

Calls `callback` on every animation frame while `active`, with the time
since the previous frame. Always calls the latest `callback`, so it can read
current props without restarting the loop. Cancelled on unmount and when
`active` turns false. Browsers pause it in background tabs.

The callback runs outside React rendering: write to a ref, a canvas, or a
style directly. Calling `setState` every frame re-renders 60+ times a second.

Use when: drawing on a canvas, a game loop, physics, or smoothing a value
that follows the pointer.
Don't use when: CSS transitions, CSS animations, or the Web Animations API
(`element.animate()`) can do it; they can run off the main thread. For work
every second or slower, use `useInterval`.

Other libraries call this `useRafLoop`.

@param callback - Called each frame with `deltaMs` (0 on the first frame)
and the frame timestamp `timeMs`. Can change every render.
@param active - Run while `true`. Default `true`.

@example
const canvas = useRef<HTMLCanvasElement>(null)
const x = useRef(0)
useAnimationFrame((deltaMs) => {
  x.current = (x.current + deltaMs * 0.1) % 300
  const ctx = canvas.current?.getContext('2d')
  ctx?.clearRect(0, 0, 300, 50)
  ctx?.fillRect(x.current, 10, 30, 30)
}, playing)

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useAnimationFrame.md

## useAnnounce

```ts
import { useAnnounce } from '@vincent.ri/react-tils'
function useAnnounce(): (message: string, politeness?: Politeness) => void
```

Returns `announce(message, politeness?)`, which reads a message to screen
reader users without moving focus or showing anything on screen. The same
message twice is announced twice.

`'polite'` (default) waits until the screen reader is idle; `'assertive'`
interrupts it, for errors only. One hidden live region per politeness is
shared by all components and removed when the last one unmounts. The
function is stable. Nothing runs on the server.

Use when: the result of an action isn't announced by itself: "Copied",
"Added to cart", "3 results", "Message sent", "Saved", or a validation
error that appears away from focus.
Don't use when: focus moves to the new content (a dialog, an inline
error with `aria-describedby`), or the text is in an element that already
has `role="status"` or `role="alert"`; screen readers read those anyway.

Other libraries call this `useAnnouncer`, `useLiveAnnouncer`, `LiveAnnouncer`.

@returns `announce(message, politeness?)`.

@example
const announce = useAnnounce()
const [copy] = useCopyToClipboard()
return <button onClick={async () => (await copy(url)) && announce('Link copied')}>Copy link</button>

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useAnnounce.md

## useAutosizeTextarea

```ts
import { useAutosizeTextarea } from '@vincent.ri/react-tils'
function useAutosizeTextarea(options?: AutosizeTextareaOptions): (element: HTMLTextAreaElement | null) => void
```

Grows a `<textarea>` to fit its text, up to `maxRows` lines, then scrolls.
Returns a callback ref for the textarea. Set the minimum with the textarea's
own `rows` attribute.

Resizes on typing and paste, when a controlled `value` changes from code
(e.g. cleared after sending), and when the textarea's width changes and the
text rewraps. Handles padding, borders, and `box-sizing`. Works the same in
every browser; CSS `field-sizing: content` does this natively but is not
supported everywhere yet.

Use when: chat inputs, comment boxes, or any text box that should grow
with its content.
Don't use when: the textarea has a fixed height, or every browser you
support has `field-sizing: content`.

Other libraries call this `useTextareaAutosize`, `useAutoResize`, `react-textarea-autosize`.

@param options - `maxRows`. Optional.
@returns A callback ref. Pass it to the textarea's `ref` prop.

@example
const [message, setMessage] = useState('')
const ref = useAutosizeTextarea({ maxRows: 8 })
return (
  <textarea ref={ref} rows={1} value={message} onChange={(e) => setMessage(e.target.value)} />
)

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useAutosizeTextarea.md

## useBeforeUnload

```ts
import { useBeforeUnload } from '@vincent.ri/react-tils'
function useBeforeUnload(when?: boolean): void
```

Asks the browser to confirm before the user closes the tab, reloads, or
navigates to another site, while `when` is `true`.

Browsers show their own generic message; custom text is not possible. The
listener is only added while `when` is `true`, because an active
`beforeunload` listener can stop the browser from caching the page for
instant back/forward.

Use when: a form or editor has unsaved changes.
Don't use when: you need to save data on exit; use `pagehide` or
`visibilitychange` with `navigator.sendBeacon`. This does not catch
client-side navigation (Next.js `<Link>`, router pushes); block those in
your router.

@param when - Ask for confirmation while `true`. Default `true`.

@example
const [draft, setDraft] = useState('')
useBeforeUnload(draft !== savedDraft)

Browser support: not available in Safari iOS. Safari on iOS doesn't fire `beforeunload`, so there is no warning there; save drafts as the user types instead.

Docs: https://vincentri.github.io/react-tils/hooks/useBeforeUnload.md

## useBroadcastChannel

```ts
import { useBroadcastChannel } from '@vincent.ri/react-tils'
function useBroadcastChannel<T = unknown>(name: string, onMessage?: (message: T, event: MessageEvent<T>) => void): (message: T) => void
```

Sends and receives messages between tabs, windows, and iframes of the same
origin, over a `BroadcastChannel`.

Opens the channel on mount and closes it on unmount. Always calls the latest
`onMessage`. The sender does not receive its own messages. Messages must be
structured-cloneable (plain objects, arrays, dates, maps; no functions or
class instances). Nothing happens on the server; `post` does nothing until
mounted.

Use when: telling other tabs about an event, e.g. "logged out", "cart
updated", or "this tab is now the leader".
Don't use when: you are syncing a value that should also survive a reload;
use `useLocalStorage`, which syncs across tabs too. For messages to a
specific window or iframe, use `postMessage`.

@param name - Channel name. Every tab using the same name shares the channel.
@param onMessage - Called with each message from other tabs. Can change every render.
@returns `post(message)`, stable for the life of the component.

@example
const post = useBroadcastChannel<{ type: 'logout' }>('auth', (message) => {
  if (message.type === 'logout') router.replace('/login')
})
const logout = async () => {
  await api.logout()
  post({ type: 'logout' })
}

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useBroadcastChannel.md

## useCaretPosition

```ts
import { useCaretPosition } from '@vincent.ri/react-tils'
function useCaretPosition<T extends HTMLTextAreaElement | HTMLInputElement = HTMLTextAreaElement>(): [(element: T | null) => void, CaretPosition | null]
```

The caret's position on screen in a `<textarea>` or text `<input>`, or
`null` while the field isn't focused. Returns a callback ref for the field.

Browsers don't expose caret coordinates, so this measures a hidden copy of
the field's text and styles. Updates on typing, clicks, arrow keys,
selection changes, and scrolling inside the field or the page, at most once
per frame. Coordinates are in viewport pixels, for a `position: fixed` popup.
Safe with controlled fields: it never updates state during their events.

Use when: placing an `@mention`, `/command`, emoji, or autocomplete popup
next to the caret, like in chat and comment inputs.
Don't use when: the popup can sit below the whole field; position it from
the field's own box. For rich text editors, use the editor's selection
API; for text selected elsewhere on the page, use `useTextSelection`.

Other libraries call this `useCaretCoordinates`, `textarea-caret`.

@returns `[ref, position]`. Pass `ref` to the textarea or input.

@example
const [ref, caret] = useCaretPosition()
const [text, setText] = useState('')
const mentioning = /@\w*$/.test(text)
return (
  <>
    <textarea ref={ref} value={text} onChange={(e) => setText(e.target.value)} />
    {mentioning && caret && (
      <ul style={{ position: 'fixed', top: caret.top + caret.height, left: caret.left }}>…</ul>
    )}
  </>
)

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useCaretPosition.md

## useClickOutside

```ts
import { useClickOutside } from '@vincent.ri/react-tils'
function useClickOutside<T extends Element = HTMLElement>(handler: (event: PointerEvent) => void, enabled?: boolean): (element: T | null) => void
```

Calls `handler` when the user presses outside an element: mouse, touch, or
pen. Returns a callback ref to put on the element.

Listens to `pointerdown` on the document, so it fires before focus moves and
works for touch. Uses `composedPath()`, so presses inside shadow DOM count
as inside.

Use when: closing a dropdown, popover, or menu when the user presses
elsewhere.
Don't use when: you can use the native `<dialog>` or the `popover`
attribute, which close on outside click and Escape with no JS. Content
rendered in a portal is outside the element: put the ref on a wrapper that
contains both, or ignore those targets in the handler. Put the ref on a
wrapper around the toggle button too: if the button is outside, pressing it
closes the menu and its click then reopens it.

Other libraries call this `useClickAway`, `useOnClickOutside`.

@param handler - Called with the `PointerEvent`. Can change every render.
@param enabled - Listen only while `true`, e.g. while the menu is open. Default `true`.
@returns A callback ref. Pass it to the element's `ref` prop.

@example
const [open, setOpen] = useState(false)
const ref = useClickOutside<HTMLDivElement>(() => setOpen(false), open)
// The ref wraps the button too, so pressing it toggles instead of closing and reopening.
return (
  <div ref={ref}>
    <button onClick={() => setOpen(!open)}>Menu</button>
    {open && <Menu />}
  </div>
)

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useClickOutside.md

## useControllableState

```ts
import { useControllableState } from '@vincent.ri/react-tils'
function useControllableState<T>(value: T | undefined, defaultValue: T, onChange?: (value: T) => void): [T, SetValue<T>]
```

State for a component that can be controlled (the parent passes `value` and
`onChange`) or uncontrolled (the parent passes only a default), like a
native `<input>` with `value` or `defaultValue`.

Returns `[value, setValue]` like `useState`. `setValue` calls `onChange`
only when the value actually changes, and accepts an updater function that
sees the latest value, also for several calls in one event. Controlled while
`value` is not `undefined`; don't switch between the two.

Use when: building a reusable component (tabs, accordion, toggle, select,
dialog `open`) whose parent may or may not want to own the state.
Don't use when: the state is only used inside one component; use `useState`.
Never copy a prop into state with `useState(prop)` + `useEffect` to sync it:
the copy goes stale or flickers. Use this hook instead.

Other libraries call this `useControlled`, `useUncontrolled`, `useControllableValue`.

@param value - The controlled value, or `undefined` when uncontrolled.
@param defaultValue - The starting value when uncontrolled.
@param onChange - Called with the new value on every change. Optional.

@example
type Props = { open?: boolean; defaultOpen?: boolean; onOpenChange?: (open: boolean) => void }
function Disclosure({ open: openProp, defaultOpen = false, onOpenChange }: Props) {
  const [open, setOpen] = useControllableState(openProp, defaultOpen, onOpenChange)
  return <button aria-expanded={open} onClick={() => setOpen((o) => !o)}>Details</button>
}

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useControllableState.md

## useCookie

```ts
import { useCookie } from '@vincent.ri/react-tils'
function useCookie(name: string, serverValue?: string | null): [string | null, (value: string, options?: CookieOptions) => void, (options?: CookieOptions) => void]
```

A cookie's value, a setter, and a remover. Unlike browser-only state, a
cookie also reaches the server with the request: pass the request's value
as `serverValue`, and the server render, hydration, and the browser all
agree from the first frame.

Re-renders when the cookie changes through this hook (in any component),
through the Cookie Store API's change event where the browser supports it,
and when the window regains focus, which catches changes made by the server
or another tab elsewhere. Values are strings, URL-encoded on write.

Use when: a preference the server must also know on the first request, so
it can render the right thing: theme, locale, currency, a dismissed banner,
or an A/B test bucket.
Don't use when: the value is sensitive (session tokens); set those as
`HttpOnly` cookies on the server, which JavaScript can't read at all. For
client-only state, `useLocalStorage` holds more and doesn't ride along on
every request.

Other libraries call this `useCookies` (react-cookie), `useCookieState`.

@param name - The cookie name.
@param serverValue - The value on the server and during hydration: read it from the request
(e.g. `(await cookies()).get('theme')?.value` in Next.js). Default `null`.
@returns `[value, set, remove]`. `set(value, options?)` writes the cookie;
`remove(options?)` deletes it (pass the same `path` and `domain` it was set with).

@example
// Server component: read the cookie from the request and pass it down.
const theme = (await cookies()).get('theme')?.value ?? null
return <ThemeToggle serverTheme={theme} />

// Client component
function ThemeToggle({ serverTheme }: { serverTheme: string | null }) {
  const [theme, setTheme] = useCookie('theme', serverTheme)
  const next = theme === 'dark' ? 'light' : 'dark'
  return <button onClick={() => setTheme(next, { maxAgeSeconds: 60 * 60 * 24 * 365 })}>{next}</button>
}

Browser support: all modern browsers. Changes made outside the hook are noticed right away where the Cookie Store API exists, and otherwise when the window regains focus.

Docs: https://vincentri.github.io/react-tils/hooks/useCookie.md

## useCopyToClipboard

```ts
import { useCopyToClipboard } from '@vincent.ri/react-tils'
function useCopyToClipboard(resetMs?: number): [(text: string) => Promise<boolean>, boolean]
```

Copies text to the clipboard and reports `copied` for a short time, for a
"Copied!" label.

`copy` resolves to `true` on success and `false` when the browser refuses
(no permission, insecure context, or no Clipboard API). Copying again
restarts the timer. The timer is cleared on unmount.

Use when: a "Copy" button for a code snippet, link, or API key.
Don't use when: you need to copy rich content (HTML, images); call
`navigator.clipboard.write()` with a `ClipboardItem`. Call `copy` from a
user action (click, keypress); browsers block clipboard writes otherwise.

@param resetMs - How long `copied` stays `true`. Default `2000`.
@returns `[copy, copied]`.

@example
const [copy, copied] = useCopyToClipboard()
return <button onClick={() => copy(apiKey)}>{copied ? 'Copied!' : 'Copy'}</button>

Browser support: all modern browsers. Needs a secure page (HTTPS or localhost). `copy` resolves to `false` when the browser refuses.

Docs: https://vincentri.github.io/react-tils/hooks/useCopyToClipboard.md

## useDebouncedCallback

```ts
import { useDebouncedCallback } from '@vincent.ri/react-tils'
function useDebouncedCallback<A extends unknown[]>(callback: (...args: A) => void, delayMs: number, options?: {
  maxWaitMs?: number
```

Returns a debounced version of `callback`: it runs `delayMs` after the last
call, with the arguments of that last call. The returned function is stable
and always runs the latest `callback`, so it can read current state.

A pending call is dropped on unmount (call `flush` first to keep it) and
when `delayMs` or `maxWaitMs` change. With `maxWaitMs`, a burst of calls
still runs at least that often.

Use when: search-as-you-type requests, autosaving a draft, or validating an
input after the user pauses.
Don't use when: you only want to keep typing responsive while rendering
something expensive; use React's `useDeferredValue`. To keep running during
a burst (live results, sending positions), use `useThrottledCallback`. For scroll or resize
values, prefer the dedicated hooks, which already avoid extra re-renders.

With Chinese, Japanese, or Korean input, skip calls while
`e.nativeEvent.isComposing` is true and call it in `onCompositionEnd`, or
it runs on half-composed text.

Other libraries call this `useDebounceCallback`, `useDebounceFn`.

@param callback - The function to debounce. Can change every render.
@param delayMs - Wait this long after the last call.
@param options - `maxWaitMs`: run at least this often during a burst. Optional.
@returns The debounced function, with `cancel`, `flush`, and `pending`.

@example
const search = useDebouncedCallback((query: string) => fetchResults(query), 300)
return <input onChange={(e) => search(e.target.value)} />

// Autosave while typing, at least every 5s, and save on unmount.
const save = useDebouncedCallback(saveDraft, 1000, { maxWaitMs: 5000 })
useEffect(() => () => save.flush(), [save])

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useDebouncedCallback.md

## useDebouncedValue

```ts
import { useDebouncedValue } from '@vincent.ri/react-tils'
function useDebouncedValue<T>(value: T, delayMs: number): T
```

Returns `value`, but only after it has stopped changing for `delayMs`.
Starts as `value` (also on the server), then lags behind while it changes.

Use when: deriving a request from fast-changing state, e.g. fetching search
results for a query typed into a controlled input.
Don't use when: you have an event handler to debounce instead of a value;
use `useDebouncedCallback`, which also has `cancel` and `flush`. To keep
typing responsive while rendering something expensive, use React's
`useDeferredValue`, which has no fixed delay.

With Chinese, Japanese, or Korean input, the text changes in steps while a
character is composed. Keep the input's own state updating, and debounce a
separate query that you set only when `e.nativeEvent.isComposing` is false
and in `onCompositionEnd`.

Other libraries call this `useDebounce`, `useDebounceValue`.

@param value - The value to debounce. Compared with `Object.is`: pass a
primitive or a memoized object. A new array or object every render
re-renders every `delayMs` forever.
@param delayMs - How long `value` must stay unchanged.

@example
const [query, setQuery] = useState('')
const debouncedQuery = useDebouncedValue(query, 300)
const results = useSearch(debouncedQuery) // your data-fetching hook
return <input value={query} onChange={(e) => setQuery(e.target.value)} />

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useDebouncedValue.md

## useDeviceOrientation

```ts
import { useDeviceOrientation } from '@vincent.ri/react-tils'
function useDeviceOrientation(): DeviceOrientationState
```

The device's orientation from its motion sensors: compass direction
(`alpha`) and tilt (`beta`, `gamma`), updated as it moves.

On iOS the user must allow motion access, and the request only works from
a tap: until then `needsPermission` is `true`, so show a button that calls
`requestPermission()`. Browsers that don't require it (Chrome, Firefox)
send readings right away, and `needsPermission` turns `false` on the first
one.
Laptops and desktops usually have no sensor, so `orientation` stays `null`.
Re-renders on every reading, up to about 60 times a second.

Use when: tilt effects, a compass, steering in a game, or a "level" tool.
Don't use when: you only need portrait or landscape; use
`useMediaQuery('(orientation: portrait)')`. For the user's position, use
`useGeolocation`.

Other libraries call this `useOrientation` (react-use), `useDeviceMotion`, `useGyroscope`.

@returns `{ orientation, needsPermission, requestPermission }`.

@example
const { orientation, needsPermission, requestPermission } = useDeviceOrientation()
if (needsPermission) return <button onClick={requestPermission}>Enable tilt</button>
const tilt = orientation?.gamma ?? 0
return <div style={{ transform: `rotate(${tilt}deg)` }}>🧭</div>

Browser support: all modern browsers. iOS needs `requestPermission()` called from a tap. Desktops usually have no sensor, so `orientation` stays `null`.

Docs: https://vincentri.github.io/react-tils/hooks/useDeviceOrientation.md

## useDocumentVisibility

```ts
import { useDocumentVisibility } from '@vincent.ri/react-tils'
function useDocumentVisibility(serverValue?: DocumentVisibilityState): DocumentVisibilityState
```

The page's `document.visibilityState` (`'visible'` or `'hidden'`), updated
when the user switches tabs, minimizes the window, or locks the screen.

Renders `serverValue` on the server and during hydration, then switches to the
real state with no hydration mismatch.

Use when: pausing polling, video, animations, or timers while the page is
hidden, or refreshing data when the user comes back.
Don't use when: you need to know if an element is on screen; use
`useInView`. Don't use it to save state before the page closes;
listen for `pagehide` instead, since a hidden page may never become visible.

Other libraries call this `usePageVisibility`.

@param serverValue - State on the server and during hydration. Default `'visible'`.

@example
const visibility = useDocumentVisibility()
useEffect(() => {
  if (visibility === 'hidden') return
  const id = setInterval(refresh, 5000)
  return () => clearInterval(id)
}, [visibility])

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useDocumentVisibility.md

## useDrag

```ts
import { useDrag } from '@vincent.ri/react-tils'
function useDrag<T extends HTMLElement = HTMLElement>(onDrag: (drag: DragState) => void, options?: DragOptions): (element: T | null) => void
```

Calls `onDrag` while the user drags an element with a mouse, finger, or
pen. Returns a callback ref for the element (the handle).

Captures the pointer, so the drag keeps going when the pointer leaves the
element or the window, and ends on release or cancel. Movements under
`threshold` don't start a drag, so a click on the handle stays a click.
Text selection is blocked while dragging. Always calls the latest `onDrag`.

Use when: resizable panels and splitters, custom sliders, dragging items
on a canvas or board, or pan to scroll.
Don't use when: you only need to know a swipe happened and its direction;
use `useSwipe`. For reordering lists, a drag-and-drop library handles
keyboard access and drop targets. Give touch handles CSS
`touch-action: none`, or the browser scrolls instead of dragging.

Other libraries call this `useDraggable`, `useGesture` (`onDrag`), `usePointerDrag`.

@param onDrag - Called on every move with `dx`, `dy`, `deltaX`, `deltaY`,
`first`, `last`, and the event. Can change every render.
@param options - `enabled`, `threshold`. Optional.
@returns A callback ref. Pass it to the element to drag.

@example
// A splitter that resizes the sidebar.
const [width, setWidth] = useState(280)
const handle = useDrag(({ deltaX }) => setWidth((w) => Math.min(600, Math.max(160, w + deltaX))))
return (
  <div style={{ display: 'flex' }}>
    <aside style={{ width }}>…</aside>
    <div ref={handle} role="separator" style={{ width: 6, cursor: 'col-resize', touchAction: 'none' }} />
    <main>…</main>
  </div>
)

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useDrag.md

## useElementScroll

```ts
import { useElementScroll } from '@vincent.ri/react-tils'
function useElementScroll<T extends Element = HTMLElement>(): [(element: T | null) => void, ElementScroll]
```

The scroll position of a scrollable element, and whether it is at each edge.
Returns a callback ref for the element.

Updates on scroll, and also when the element or its content changes size
with no scroll event (rows added, text streamed in), so `atBottom` never
goes stale. Before the element is measured, and on the server, it is at
`0, 0` with every edge `true`.

Use when: fade shadows at the edges of a scrolling table or list, a "scroll
to top" button inside a panel, or "you've read to the end" in a container.
Don't use when: the page itself scrolls; use `useWindowScroll`. For a chat
that follows new messages, use `useStickToBottom`. Shadows alone can be done
with CSS scroll-driven animations where supported.

Re-renders as `x` and `y` change, about once a frame while scrolling. If
an expensive component only needs the edge flags, call the hook in a small
child component instead.

Other libraries call this `useScroll`.

@returns `[ref, scroll]`. Pass `ref` to the scrollable element.

@example
const [ref, { atTop, atBottom }] = useElementScroll<HTMLDivElement>()
return (
  <div ref={ref} style={{ overflow: 'auto', maxHeight: 400 }}
    className={[!atTop && 'shadow-top', !atBottom && 'shadow-bottom'].filter(Boolean).join(' ')}>
    <Rows />
  </div>
)

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useElementScroll.md

## useElementSize

```ts
import { useElementSize } from '@vincent.ri/react-tils'
function useElementSize<T extends Element = HTMLElement>(options?: ElementSizeOptions): [(element: T | null) => void, ElementSize]
```

An element's size in CSS pixels, updated whenever it resizes. By default the
content box (excluding padding and border); pass `{ box: 'border-box' }` to
include them, e.g. to match `getBoundingClientRect()` without transforms.

Returns a callback ref to put on the element. The size is `{ width: 0,
height: 0 }` on the server and until the element is measured. Measurement
starts in a layout effect, so in the browser the real size is usually ready
before the first paint.

Use when: JS needs an element's pixel size, e.g. sizing a canvas or chart to
its container, or choosing how many items fit in a row.
Don't use when: only styles depend on the size; use CSS container queries,
which need no JS. For the window, use `useWindowSize`.

Other libraries call this `useMeasure`, `useSize`, `useResizeObserver`.

@param options - `box`: which box to measure. Default `'content-box'`.
@returns `[ref, size]`. Pass `ref` to the element's `ref` prop.

@example
const [ref, { width, height }] = useElementSize<HTMLDivElement>()
return (
  <div ref={ref} style={{ height: 300 }}>
    <Chart width={width} height={height} />
  </div>
)

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useElementSize.md

## useEventListener

```ts
import { useEventListener } from '@vincent.ri/react-tils'
function useEventListener<T extends EventListenerTarget, K extends (keyof EventMapFor<T> & string) | (string & {})>(target: T, type: K, handler: (event: EventFor<T, K>) => void, options?: Pick<AddEventListenerOptions, "capture" | "passive" | "once">): void
```

Adds an event listener and removes it on unmount, like `addEventListener`
in an effect, but always calls the latest `handler` without re-subscribing.

Pass `'window'` or `'document'` as strings (safe on the server), an element,
a ref object, or `null` to not listen. Re-subscribes only when the target,
`type`, or options change.

Use when: no dedicated hook covers the event, e.g. `keydown` for a game,
`message` from an iframe, or `pointermove` while dragging.
Don't use when: a dedicated hook exists (`useWindowSize`, `useOnline`,
`useHotkey`, `useClickOutside`, ...); they also give a server value and
avoid re-renders. For element events in your own JSX, use props like
`onClick`.

@param target - `'window'`, `'document'`, an `EventTarget`, a ref, or `null`.
@param type - The event name, e.g. `'keydown'`, or a custom event name.
@param handler - Called with the event. Can change every render.
@param options - `capture`, `passive`, `once`. Same as `addEventListener`.

@example
useEventListener('window', 'message', (event) => {
  if (event.origin === 'https://widget.example.com') setData(event.data)
})

const ref = useRef<HTMLDivElement>(null)
useEventListener(ref, 'pointermove', (event) => setX(event.clientX), { passive: true })

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useEventListener.md

## useEventSource

```ts
import { useEventSource } from '@vincent.ri/react-tils'
function useEventSource(url: string | null, options?: EventSourceOptions): EventSourceState
```

Live updates from the server over Server-Sent Events (`EventSource`):
connects while `url` is set, closes on unmount or when `url` changes or is
`null`, and reconnects on its own.

Browsers retry dropped connections themselves, but give up for good when
the server answers with an error status; this hook keeps retrying then,
waiting 1s, 2s, 4s, up to 30s between attempts. With `pauseWhenHidden`, a
background tab holds no connection.

`data` is only the latest message: when several arrive at once, a render
may see just the last. To keep every message (a feed, a log), use
`onMessage`. Messages are strings; `JSON.parse` them yourself.

Use when: one-way live updates: notifications, progress of a job, live
scores or prices, a dashboard, logs.
Don't use when: streaming an AI response from a `POST`; `EventSource` can
only `GET` and can't set headers, so read `fetch()`'s body stream (or use
your AI SDK). For two-way messaging, use a WebSocket library. To check for
changes every minute or so, polling with `useInterval` is simpler.

Other libraries call this `useEventSource` (VueUse), `useSSE`, `useServerSentEvents`.

@param url - The stream's URL, or `null` to stay disconnected.
@param options - `onMessage`, `events`, `withCredentials`, `pauseWhenHidden`. Optional.
@returns `{ status, data }`.

@example
const { status, data } = useEventSource(`/api/jobs/${id}/progress`)
const percent = data ? JSON.parse(data).percent : 0
return <progress value={percent} max={100} aria-busy={status !== 'open'} />

// Keep every message
const [items, setItems] = useState<Notification[]>([])
useEventSource('/api/notifications', {
  onMessage: (event) => setItems((list) => [JSON.parse(event.data), ...list]),
  pauseWhenHidden: true,
})

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useEventSource.md

## useFileDrop

```ts
import { useFileDrop } from '@vincent.ri/react-tils'
function useFileDrop<T extends HTMLElement = HTMLElement>(onDrop: (files: File[], event: DragEvent) => void, options?: {
  enabled?: boolean
```

Turns an element into a drop zone for files, and reports when files are
dragged over it.

`isOver` does not flicker when the pointer moves over child elements (it
counts enter/leave pairs). Only reacts to drags that carry files, so dragging
text or links inside the page is unaffected. Prevents the browser from
opening a file dropped on the zone. Returns a callback ref for the element.

Use when: an upload area, an "import file" panel, or dropping images into an
editor.
Don't use when: a plain `<input type="file">` is enough; keep one anyway as
the keyboard and screen-reader accessible way to pick files. Filter file
types and sizes in `onDrop`; the browser doesn't.

@param onDrop - Called with the dropped files. Can change every render.
@param options - `enabled`: accept drops while `true`. Default `true`.
@returns `[ref, isOver]`. Pass `ref` to the drop zone's `ref` prop.

@example
const [ref, isOver] = useFileDrop((files) => upload(files.filter((f) => f.type.startsWith('image/'))))
return (
  <div ref={ref} className={isOver ? 'zone active' : 'zone'}>
    Drop images here, or <input type="file" accept="image/*" multiple onChange={(e) => upload([...e.target.files!])} />
  </div>
)

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useFileDrop.md

## useFocusTrap

```ts
import { useFocusTrap } from '@vincent.ri/react-tils'
function useFocusTrap<T extends HTMLElement = HTMLElement>(active?: boolean): (element: T | null) => void
```

Keeps keyboard focus inside an element while `active`, e.g. a custom modal
or drawer. Returns a callback ref for the element.

On activation, focuses the element with `autofocus` inside, else the first
focusable element, else the container itself. Tab and Shift+Tab move through
the focusable elements in DOM order and wrap around, the same in every
browser (Safari otherwise skips buttons). If focus moves outside (e.g. a click elsewhere), it is brought back.
On deactivation or unmount, focus returns to the element that had it before,
usually the button that opened the dialog.

Use when: a custom modal, drawer, or full-screen menu that you can't build
with `<dialog>`.
Don't use when: you can use `<dialog>` with `showModal()`; it traps focus,
restores it, closes on Escape, and makes the rest of the page inert, with no
JS. A focus trap alone doesn't hide the page from screen readers: also set
`aria-modal="true"` on the dialog, or `inert` on the rest of the page.

@param active - Trap focus while `true`. Default `true`.
@returns A callback ref. Pass it to the container's `ref` prop.

@example
function Drawer({ open, onClose }: { open: boolean; onClose: () => void }) {
  const ref = useFocusTrap<HTMLDivElement>(open)
  useHotkey('Escape', onClose, { enabled: open })
  if (!open) return null
  return (
    <div ref={ref} role="dialog" aria-modal="true" aria-label="Menu">
      <button onClick={onClose}>Close</button>
      <nav>…</nav>
    </div>
  )
}

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useFocusTrap.md

## useFocusWithin

```ts
import { useFocusWithin } from '@vincent.ri/react-tils'
function useFocusWithin<T extends Element = HTMLElement>(options?: FocusWithinOptions): [(element: T | null) => void, boolean]
```

Whether focus is on the element or anything inside it, like CSS
`:focus-within`, with callbacks when focus enters or leaves. Moving focus
between children inside doesn't count as leaving.

Switching to another window or tab doesn't count either: focus is still
there when the user comes back. Content in a React portal is outside in the
DOM, so focus moving into it counts as leaving: put the ref on an element
that contains the portal's target too.

Use when: closing a menu, popover, or combobox list when keyboard users Tab
out of it, which `useClickOutside` alone misses; saving or collapsing an
inline editor when focus leaves it; showing toolbar actions while a
composer is focused.
Don't use when: only styling; use CSS `:focus-within`. For a modal, keep
focus inside with `useFocusTrap` instead. On iOS, tapping a button doesn't
focus it, so pair this with `useClickOutside` for pointer users.

Other libraries call this `useFocusWithin` (react-aria, Mantine), `useFocusOutside`.

@param options - `onEnter`, `onLeave`. Optional; can change every render.
@returns `[ref, focused]`.

@example
const [open, setOpen] = useState(false)
const outsideRef = useClickOutside(() => setOpen(false), open)
const [focusRef] = useFocusWithin({ onLeave: () => setOpen(false) })
const ref = useMergedRefs(outsideRef, focusRef)
return (
  <div ref={ref}>
    <button onClick={() => setOpen(!open)}>Menu</button>
    {open && <ul>…</ul>}
  </div>
)

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useFocusWithin.md

## useFullscreen

```ts
import { useFullscreen } from '@vincent.ri/react-tils'
function useFullscreen<T extends Element = HTMLElement>(): [(element: T | null) => void, Fullscreen]
```

Puts an element into fullscreen and tracks whether it is, including when
the user leaves with Esc or a browser control.

Returns a callback ref for the element and controls. `enter` must be called
from a user action (click, keypress); browsers refuse otherwise.

Use when: a fullscreen button for a video player, image viewer, slideshow,
game, or map.
Don't use when: you only need a large layout; use CSS (`position: fixed;
inset: 0`). On iPhone, only `<video>` can go fullscreen, through the video's
own controls, so check `supported` before showing the button.

@returns `[ref, { supported, active, enter, exit, toggle }]`.

@example
const [ref, fullscreen] = useFullscreen<HTMLDivElement>()
return (
  <div ref={ref}>
    <Slides />
    {fullscreen.supported && (
      <button onClick={fullscreen.toggle}>{fullscreen.active ? 'Exit' : 'Fullscreen'}</button>
    )}
  </div>
)

Browser support: not available in Safari iOS. `supported` is `false` where `document.fullscreenEnabled` isn't true, including on iPhone, where Safari allows fullscreen only for `<video>`.

Docs: https://vincentri.github.io/react-tils/hooks/useFullscreen.md

## useGeolocation

```ts
import { useGeolocation } from '@vincent.ri/react-tils'
function useGeolocation(options?: GeolocationOptions): GeolocationState
```

The device's position, watched with `navigator.geolocation.watchPosition`
and updated as it moves. Stops watching on unmount or when disabled.

Enabling it makes the browser ask the user for permission the first time,
so pass `enabled: false` until the user asks for location (e.g. clicks "Use
my location"). On the server and during hydration it returns the initial
state: `loading` if enabled, with no position.

Use when: showing the user on a map, sorting nearby results, or filling in a
location after the user asks.
Don't use when: a rough region is enough; use IP-based location on the
server, which needs no prompt. Don't enable it on page load: users deny
unexpected prompts, and a denial is hard to undo. To check the permission
without prompting, use `usePermission('geolocation')`.

@param options - `enabled`, `enableHighAccuracy`, `maximumAge`, and `timeout`.
All optional.

@example
const [asked, setAsked] = useState(false)
const { loading, position, error } = useGeolocation({ enabled: asked })
if (!asked) return <button onClick={() => setAsked(true)}>Use my location</button>
if (loading) return <p>Locating…</p>
if (error) return <p>Could not get your location: {error.message}</p>
return <Map lat={position!.coords.latitude} lng={position!.coords.longitude} />

Browser support: all modern browsers. Needs a secure page (HTTPS or localhost).

Docs: https://vincentri.github.io/react-tils/hooks/useGeolocation.md

## useHash

```ts
import { useHash } from '@vincent.ri/react-tils'
function useHash(serverValue?: string): [string, (hash: string) => void]
```

The URL hash, like `location.hash` (`'#pricing'`, or `''` when there is
none), and a setter. Re-renders on hash links, back/forward, `setHash`, and
router navigation that uses `history.pushState` (e.g. Next.js `<Link
href="#pricing">`, in browsers with the Navigation API).

The server never sees the hash, so the server render and hydration use
`serverValue`, then the real hash with no hydration mismatch.

Use when: tabs or an open panel that should survive reload and be linkable
(`/settings#billing`), or highlighting the section a link pointed to.
Don't use when: the state must reach the server or appear in search
results; use a query param (`useSearchParam`, or your router's). To style the target
element, use CSS `:target`.

@param serverValue - Value on the server and during hydration. Default `''`.
@returns `[hash, setHash]`. `setHash('#billing')` (or `'billing'`) adds a
history entry and scrolls to a matching `id`, like clicking a hash link.

@example
const [hash, setHash] = useHash()
const tab = hash === '#billing' ? 'billing' : 'profile'
return <button onClick={() => setHash('#billing')}>Billing</button>

Browser support: all modern browsers. Router navigation that changes the URL with `history.pushState` (e.g. Next.js `<Link>`) is noticed only where the Navigation API exists. Elsewhere the hash still updates on links, Back and Forward, and the hook's own setter.

Docs: https://vincentri.github.io/react-tils/hooks/useHash.md

## useHotkey

```ts
import { useHotkey } from '@vincent.ri/react-tils'
function useHotkey(hotkey: string, handler: (event: KeyboardEvent) => void, options?: HotkeyOptions): void
```

Calls `handler` when a keyboard shortcut is pressed, e.g. `'Escape'`,
`'mod+k'`, `'shift+/'`.

`mod` is Cmd on Apple devices and Ctrl elsewhere. Modifiers must match
exactly, so `'k'` does not fire for Ctrl+K. Ignored during IME composition,
and while typing in inputs, textareas, selects, and contenteditable, except
Escape. Key names follow `KeyboardEvent.key`, case-insensitive; `esc` and
`space` work as aliases.

Use when: global shortcuts like a command palette (`mod+k`), closing a
modal with Escape, or `/` to focus search.
Don't use when: the shortcut belongs to one focused element; use its
`onKeyDown` prop. For text input handling, use the input's own events.

Other libraries call this `useKey`, `useKeyPress`, `useHotkeys`.

@param hotkey - Modifiers and a key joined by `+`: `ctrl`, `alt`, `shift`, `meta`, `mod`.
Separate steps with spaces for a sequence: `'g i'` fires after g then i,
each within a second of the previous one.
@param handler - Called with the `KeyboardEvent`. Can change every render.
@param options - `enabled`, `preventDefault`, `enableInInputs`. All optional.

@example
useHotkey('mod+k', () => setPaletteOpen(true))
useHotkey('Escape', () => setPaletteOpen(false), { enabled: paletteOpen })

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useHotkey.md

## useHydrated

```ts
import { useHydrated } from '@vincent.ri/react-tils'
function useHydrated(): boolean
```

`false` on the server and during hydration, `true` once the component is
running in the browser.

On a client-side mount after the page has hydrated, it is `true` from the
first render, so there is no flash. This replaces the
`useState(false)` + `useEffect(() => setMounted(true))` pattern, which
renders `false` first on every mount.

Use when: rendering something that only makes sense in the browser, e.g. a
locale-formatted date or time, a client-only widget, or a "copy to
clipboard" button that needs browser APIs.
Don't use when: you need a specific browser value (viewport, storage,
network); use the hook for that value, which also renders the right thing
on the server. Don't use it to hide hydration mismatches you could fix.

Other libraries call this `useIsClient`, `useMounted`.

@example
const hydrated = useHydrated()
return <time>{hydrated ? date.toLocaleString() : date.toISOString()}</time>

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useHydrated.md

## useIdle

```ts
import { useIdle } from '@vincent.ri/react-tils'
function useIdle(timeoutMs?: number): boolean
```

Whether the user has been inactive (no pointer, keyboard, touch, wheel, or
scroll input) for `timeoutMs`. Becomes `false` again on the next activity.

`false` on the server, during hydration, and on mount: a user who just
loaded the page counts as active. Activity only records a timestamp, and a
single timer checks it, so mouse movement does not re-render.

Use when: showing "Are you still there?" before a session timeout, pausing
expensive live updates, or setting a chat status to "away".
Don't use when: you mean "the tab is hidden"; use `useDocumentVisibility`.
Activity inside an `<iframe>` (an embedded video or payment form) isn't
seen, so a user busy there can turn idle.
Don't use it alone to log users out for security; enforce session expiry on
the server.

@param timeoutMs - Milliseconds without activity before idle. Default `60_000`.

@example
const idle = useIdle(5 * 60_000)
return idle ? <Dialog>Are you still there?</Dialog> : null

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useIdle.md

## useInView

```ts
import { useInView } from '@vincent.ri/react-tils'
function useInView<T extends Element = HTMLElement>(options?: InViewOptions): [(element: T | null) => void, boolean]
```

Whether an element is visible in the viewport, using IntersectionObserver.

Returns a callback ref to put on the element. It is `false` on the server,
during hydration, and until the observer first reports. Does not re-render
on scroll, only when visibility changes.

Use when: lazy-loading content or images, loading the next page of an
infinite list, starting an animation or video when it scrolls into view, or
tracking impressions.
Don't use when: you need the exact scroll position; use `useWindowScroll`.
For images alone, `<img loading="lazy">` needs no JS.

Other libraries call this `useIntersection`, `useIntersectionObserver`, `useInViewport`.

@param options - `rootMargin`, `threshold`, and `once`. All optional.
@returns `[ref, inView]`. Pass `ref` to the element's `ref` prop.

@example
// Load more when the sentinel gets within 300px of the viewport.
const [ref, inView] = useInView<HTMLDivElement>({ rootMargin: '300px' })
useEffect(() => {
  if (inView) loadMore()
}, [inView])
return <div ref={ref} />

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useInView.md

## useInterval

```ts
import { useInterval } from '@vincent.ri/react-tils'
function useInterval(callback: () => void, delayMs: number | null, options?: IntervalOptions): void
```

Calls `callback` every `delayMs` milliseconds. Pass `null` as the delay to
pause. Always calls the latest `callback`, so it can read current state
without restarting the timer.

The timer restarts only when `delayMs` changes or it is paused and resumed.
Browsers slow timers in background tabs (to once a second or less), so
don't count ticks to measure time; compare `Date.now()` or use `useNow`.
Cleared on unmount. Nothing runs on the server.

Use when: polling an API, a countdown or clock, or rotating a carousel.
Don't use when: you need a single delay; use `setTimeout` in an event
handler or effect. For animation, use CSS or `requestAnimationFrame`.
Server data that changes often may suit a data-fetching library with
built-in refetching.

@param callback - Called on every tick. Can change every render.
@param delayMs - Milliseconds between ticks, or `null` to pause.
@param options - `pauseWhenHidden`. Optional.

@example
const [count, setCount] = useState(0)
useInterval(() => setCount(count + 1), running ? 1000 : null)

// Poll every 5s, but not while the tab is in the background.
useInterval(refresh, 5000, { pauseWhenHidden: true })

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useInterval.md

## useIsStuck

```ts
import { useIsStuck } from '@vincent.ri/react-tils'
function useIsStuck<T extends Element = HTMLElement>(): [(element: T | null) => void, boolean]
```

Whether a `position: sticky` element is currently stuck to the top of the
viewport. Returns a callback ref for the sticky element.

Reads the element's own CSS `top` and watches it with an
IntersectionObserver, so it costs nothing while scrolling and needs no
extra markup. `false` on the server and until the element is measured.

Use when: adding a shadow or border to a sticky header only once it sticks,
or shrinking a sticky toolbar.
Don't use when: the sticky element sticks inside a scroll container rather
than the page; this watches the viewport. If you only need the element to
stick, CSS `position: sticky` alone is enough.

Other libraries call this `useSticky`, `useStickyFixed`.

@returns `[ref, stuck]`. Pass `ref` to the sticky element.

@example
const [ref, stuck] = useIsStuck<HTMLElement>()
return (
  <header ref={ref} style={{ position: 'sticky', top: 0 }} className={stuck ? 'shadow' : ''}>
    …
  </header>
)

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useIsStuck.md

## useLocalStorage

```ts
import { useLocalStorage } from '@vincent.ri/react-tils'
function useLocalStorage<T>(key: string, serverValue: T): [T, SetValue<T>]
```

State that persists in `localStorage` as JSON, stays in sync across
components and browser tabs, and is safe to server-render.

Renders `serverValue` on the server and during hydration, then switches to the
stored value with no hydration mismatch. Missing or unparseable stored values
also read as `serverValue`. Setting `undefined` removes the key.

Values go through JSON: a `Date` comes back as a string, and `Map`, `Set`,
`Infinity`, and `undefined` inside objects don't survive. Store plain data.
Writes made directly with `localStorage` in the same tab aren't seen; go
through the setter.

Use when: user preferences, drafts, or UI state should survive a reload or be
shared between tabs (theme, sidebar open, last tab).
Don't use when: the data is sensitive (tokens, personal data). Any script on
the page can read localStorage. Also not for large data (5 MB limit, blocks
the main thread); use IndexedDB. Not for server-needed state; use cookies.

Other libraries call this `useLocalStorageState`.

@param key - The localStorage key.
@param serverValue - Value on the server, during hydration, and when nothing
valid is stored. Pass a primitive or a constant, so the setter stays stable.
@returns `[value, setValue]`, like `useState`. `setValue` accepts a value or
an updater. If storage is full or blocked, the value still updates for this
page session but isn't saved.

@example
const [theme, setTheme] = useLocalStorage<'light' | 'dark'>('theme', 'light')
setTheme('dark')

const [count, setCount] = useLocalStorage('count', 0)
setCount((c) => c + 1)

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useLocalStorage.md

## useLongPress

```ts
import { useLongPress } from '@vincent.ri/react-tils'
function useLongPress(onLongPress: (event: PointerEvent) => void, options?: LongPressOptions): LongPressHandlers
```

Calls `onLongPress` when the user presses and holds an element, with mouse,
touch, or pen. Returns event handlers to spread onto the element.

Cancels if the pointer is released, leaves, or moves past `moveTolerance`
(so scrolling on a phone doesn't trigger it). Only the primary button
counts. After a long press, the click that follows is swallowed, so the
element's `onClick` doesn't also run, and the mobile context menu is
suppressed while holding.

Use when: secondary actions on touch devices, e.g. select an item in a list,
show a preview, or "hold to delete".
Don't use when: it is the only way to reach an action; long press is hard to
discover and not keyboard accessible, so offer a button or menu too. Add CSS
`user-select: none; -webkit-touch-callout: none` on the element to stop text
selection on iOS.

@param onLongPress - Called with the original pointer event once the hold completes.
@param options - `delayMs` and `moveTolerance`. Optional.
@returns Handlers to spread onto the element.

@example
const longPress = useLongPress(() => setSelected(item.id))
return (
  <li {...longPress} onClick={() => open(item)}>
    {item.name}
  </li>
)

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useLongPress.md

## useMediaQuery

```ts
import { useMediaQuery } from '@vincent.ri/react-tils'
function useMediaQuery(query: string, serverValue?: boolean): boolean
```

Tracks whether a CSS media query matches, and re-renders when it changes.

Renders `serverValue` on the server and during hydration, then switches to the
real value with no hydration mismatch. Concurrent-safe: every component reads
the same value in one render.

Use when: JS logic depends on viewport size, `prefers-color-scheme`,
`prefers-reduced-motion`, pointer type, or orientation.
Don't use when: only styling changes. Use a CSS `@media` rule instead, which
needs no JS and never flashes.

Other libraries call this `useMedia`, `useBreakpoint`, `useResponsive`.

@param query - Any CSS media query, e.g. `'(min-width: 768px)'`.
@param serverValue - Value on the server and during hydration. Pick the value
most visitors will have, to minimize the switch after hydration. Default `false`.

@example
const isWide = useMediaQuery('(min-width: 768px)')
const prefersDark = useMediaQuery('(prefers-color-scheme: dark)')
// Mobile-first site: assume narrow on the server.
const isDesktop = useMediaQuery('(min-width: 1024px)', false)

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useMediaQuery.md

## useMediaRecorder

```ts
import { useMediaRecorder } from '@vincent.ri/react-tils'
function useMediaRecorder(stream: MediaStream | null, options?: MediaRecorderOptions): MediaRecorderState
```

Records a `MediaStream` (microphone, camera, or screen) into a file. Pair
it with `useUserMedia` for the stream.

Picks a format the browser can actually record: Chrome and Firefox record
WebM, Safari records MP4, so a hardcoded `audio/webm` fails in Safari.
`stop()` resolves with the finished `Blob` once the recorder has delivered
its last chunk. Recording stops on unmount and when `stream` changes; the
stream itself is left running, so stop its tracks yourself (`useUserMedia`
does that on unmount).

Use when: voice notes, voice input for an AI chat (record, then send to a
transcription API), recording a video message, or a screen recording.
Don't use when: you want live speech-to-text in the browser; that is the
Web Speech API. To only show a camera or microphone preview, use
`useUserMedia` alone.

Other libraries call this `useRecorder`, `useAudioRecorder`, `react-media-recorder`.

@param stream - The stream to record, or `null` until it's ready.
@param options - `mimeTypes`: formats to try, in order. Optional.
@returns `{ supported, recording, mimeType, blob, error, start, stop }`.

@example
const [on, setOn] = useState(false)
const { stream } = useUserMedia({ audio: true }, { enabled: on })
const recorder = useMediaRecorder(stream)
const finish = async () => {
  const blob = await recorder.stop()
  if (blob) await transcribe(new File([blob], 'note', { type: blob.type }))
  setOn(false)
}
return recorder.recording
  ? <button onClick={finish}>Stop</button>
  : <button onClick={() => (stream ? recorder.start() : setOn(true))}>{stream ? 'Record' : 'Allow microphone'}</button>

Browser support: all modern browsers. Browsers record different formats (Safari records MP4, others WebM); the hook picks one the browser supports and reports it as `mimeType`.

Docs: https://vincentri.github.io/react-tils/hooks/useMediaRecorder.md

## useMergedRefs

```ts
import { useMergedRefs } from '@vincent.ri/react-tils'
function useMergedRefs<T>(...refs: (Ref<T> | undefined)[]): (element: T | null) => void
```

Combines several refs into one callback ref, so one element can have a
`useRef`, a forwarded `ref` prop, and refs from hooks such as `useInView`
and `useElementSize` at the same time.

Accepts ref objects, callback refs, `null`, and `undefined`. The merged ref
never changes; when one of the refs changes, the element moves to the new
ref right after render. Works with React 18, with React 19 callback refs
that return a cleanup function, and with React Compiler.

Use when: two or more refs must point at the same element.
Don't use when: there is only one ref; pass it directly.

Other libraries call this `useMergeRefs`, `useForkRef`, `mergeRefs`.

@param refs - The refs to set.

@example
function Section({ ref }: { ref?: Ref<HTMLElement> }) {
  const [inViewRef, inView] = useInView<HTMLElement>()
  const [sizeRef, { width }] = useElementSize<HTMLElement>()
  return <section ref={useMergedRefs(ref, inViewRef, sizeRef)}>…</section>
}

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useMergedRefs.md

## useNetworkInformation

```ts
import { useNetworkInformation } from '@vincent.ri/react-tils'
function useNetworkInformation(serverValue?: NetworkInfo): NetworkInfo
```

The connection's data-saver setting and rough quality, from the Network
Information API, updated when it changes.

Only Chromium browsers report it; elsewhere every field is unknown
(`saveData: false`, `effectiveType: 'unknown'`), so treat unknown as a
normal connection. Renders `serverValue` on the server and during hydration.

Use when: adapting heavy content, e.g. don't autoplay video or prefetch when
`saveData` is on or the connection is `'2g'`/`'slow-2g'`.
Don't use when: choosing image sizes; `<img srcset sizes>` lets the browser
decide. On the server, the `Save-Data` request header gives the same signal
before any JS runs. Don't block features on it: the estimates are rough.

@param serverValue - Value on the server and during hydration. Default: all unknown.

@example
const { saveData, effectiveType } = useNetworkInformation()
const lite = saveData || effectiveType === '2g' || effectiveType === 'slow-2g'
return lite ? <img src={poster} alt="" /> : <video src={clip} autoPlay muted loop />

Browser support: not available in Firefox, Safari, Safari iOS. Where the API is missing, every field stays unknown: `effectiveType: 'unknown'`, `saveData: false`, and `null` estimates.

Docs: https://vincentri.github.io/react-tils/hooks/useNetworkInformation.md

## useNow

```ts
import { useNow } from '@vincent.ri/react-tils'
function useNow<S extends number | null = null>(intervalMs: number, serverValue?: S): number | S
```

The current time as a timestamp in milliseconds, rounded down to
`intervalMs` and updated every `intervalMs`. Ticks land on whole intervals
(a 1000 ms clock changes exactly on the second), so every component using
the same interval shows the same time.

The server and the client never agree on the time, so `new Date()` in render
causes a hydration mismatch. This hook returns `serverValue` (default
`null`) on the server and during hydration, then the real time.

Use when: a clock, a countdown, "5 minutes ago" labels, or anything else that
renders the current time.
Don't use when: you need to run code on a schedule rather than render the
time; use `useInterval`. For a time read once, call `Date.now()` in an event
handler.

@param intervalMs - How often to update, and the precision of the value.
@param serverValue - Value on the server and during hydration, e.g. the
request time passed from the server. Default `null`.

@example
const now = useNow(1000)
return <time>{now === null ? '--:--:--' : new Date(now).toLocaleTimeString()}</time>

// Relative time, updated every minute.
const now = useNow(60_000)
const minutes = now === null ? 0 : Math.round((now - sentAt) / 60_000)

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useNow.md

## useOnline

```ts
import { useOnline } from '@vincent.ri/react-tils'
function useOnline(serverValue?: boolean): boolean
```

Whether the browser has a network connection, and re-renders when it changes.

Renders `serverValue` on the server and during hydration, then switches to
`navigator.onLine` with no hydration mismatch.

Use when: showing an offline banner, disabling actions that need the network,
or queueing writes until the connection is back.
Don't use when: you need to know a server is reachable. `true` only means the
device has a network (it can still be a captive portal or a dead Wi-Fi), so
handle request failures anyway.

Other libraries call this `useNetworkState`, `useNetwork`.

@param serverValue - Value on the server and during hydration. Default `true`,
since most visitors are online.

@example
const online = useOnline()
return online ? null : <Banner>You are offline. Changes will sync later.</Banner>

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useOnline.md

## usePageRestore

```ts
import { usePageRestore } from '@vincent.ri/react-tils'
function usePageRestore(callback: (event: PageTransitionEvent) => void): void
```

Calls `callback` when the browser restores the page from its back/forward
cache, e.g. the user comes back with the Back button. The page reappears
exactly as it was left: no reload, no new render, no effects re-run, so
data shown on it may be stale.

Always calls the latest `callback`. Nothing runs on the server or on a
normal page load.

Use when: refreshing a cart, notifications, prices, or anything else that
may have changed while the user was on another page, or resetting UI such
as an open menu or a "Submitting…" button left over from before.
Don't use when: you want to know when the tab becomes visible again; use
`useDocumentVisibility`. Avoid `unload` listeners anywhere on the page:
they stop browsers from caching it at all.

Other libraries call this `useBfcache`, `usePageShow`.

@param callback - Called with the `pageshow` event. Can change every render.

@example
const { data, refetch } = useCart() // your data-fetching hook
usePageRestore(() => refetch())

// Reset a form that was left mid-submit before navigating away.
usePageRestore(() => setSubmitting(false))

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/usePageRestore.md

## usePasteFiles

```ts
import { usePasteFiles } from '@vincent.ri/react-tils'
function usePasteFiles<T extends HTMLElement = HTMLElement>(onFiles: (files: File[], event: ClipboardEvent) => void, options?: PasteFilesOptions): (element: T | null) => void
```

Calls `onFiles` when the user pastes files, such as a screenshot, while
focus is inside an element. Returns a callback ref for the element, e.g. a
chat input or its wrapper.

Only pastes that contain matching files are taken: their default is
prevented so the file name isn't pasted as text. Plain text pastes are left
alone.

Use when: pasting images into a chat, a comment box, an editor, or an
upload area.
Don't use when: you want drag and drop; use `useFileDrop` (they work well
together). Keep an `<input type="file">` too, for users who don't paste.

Other libraries call this `usePaste`, `useClipboardFiles`.

@param onFiles - Called with the pasted files and the event. Can change every render.
@param options - `enabled`, `accept`. Optional.
@returns A callback ref. Pass it to the element that contains the focused input.

@example
const ref = usePasteFiles((files) => attach(files), { accept: 'image/*' })
return <textarea ref={ref} placeholder="Message, or paste a screenshot" />

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/usePasteFiles.md

## usePermission

```ts
import { usePermission } from '@vincent.ri/react-tils'
function usePermission(name: PermissionName | (string & {})): PermissionValue
```

The current state of a browser permission (`'granted'`, `'denied'`,
`'prompt'`), updated when the user changes it in browser settings.

Returns `'unknown'` on the server, during hydration, while the browser
answers (one async query, shared by every component), and when the browser
does not support querying that permission. Never triggers a permission
prompt.

Use when: deciding whether to show a "Enable notifications" or "Use my
location" button, or explaining how to re-enable a denied permission.
Don't use when: you need to ask for the permission; call the feature's own
API from a user action (e.g. `Notification.requestPermission()`, or
`useGeolocation`). Treat `'unknown'` as "might work": support differs a lot
between browsers (e.g. Firefox and Safari don't support querying camera).

@param name - A permission name, e.g. `'geolocation'`, `'notifications'`,
`'camera'`, `'microphone'`, `'clipboard-read'`.

@example
const permission = usePermission('notifications')
if (permission === 'denied') return <p>Notifications are blocked in your browser settings.</p>
if (permission !== 'granted') return <button onClick={() => Notification.requestPermission()}>Enable notifications</button>

Browser support: all modern browsers. Browsers support different permission names; a name the browser doesn't know reports `'unknown'`.

Docs: https://vincentri.github.io/react-tils/hooks/usePermission.md

## usePointerPosition

```ts
import { usePointerPosition } from '@vincent.ri/react-tils'
function usePointerPosition<T extends Element = HTMLElement>(): [(element: T | null) => void, PointerPosition | null]
```

Where the mouse, pen, or finger is over an element, in pixels from its
top-left corner, or `null` while it's outside (and on the server). Attach
the returned ref to the element.

With a mouse it follows hovering; with a finger, only while it touches, and
it turns `null` when the finger lifts. Re-renders on every move, so keep the
component small, or skip React for pure visuals (see below).

Use when: a spotlight or glow that follows the cursor on a card, a tooltip
or magnifier at the pointer, crosshairs on a chart, or a hover preview that
depends on the position (scrubbing a video thumbnail).
Don't use when: plain hover styling (CSS `:hover`); a drag (`useDrag`); or
a page-wide custom cursor, which re-renders the whole app per move: use
`useEventListener('window', 'pointermove', …)` and set a CSS variable or
`transform` on the element directly.

Other libraries call this `useMouse` (react-use), `useMousePosition`, `usePointer`.

@returns `[ref, position]`: `position` is `{ x, y }`, or `null` while the pointer is outside.

@example
const [ref, pointer] = usePointerPosition<HTMLDivElement>()
return (
  <div
    ref={ref}
    className="card"
    style={{ '--x': `${pointer?.x ?? -999}px`, '--y': `${pointer?.y ?? -999}px` } as CSSProperties}
  />
)
// .card { background: radial-gradient(200px at var(--x) var(--y), #fff3, transparent) }

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/usePointerPosition.md

## usePreferredLanguages

```ts
import { usePreferredLanguages } from '@vincent.ri/react-tils'
function usePreferredLanguages(serverValue?: readonly string[]): readonly string[]
```

The user's preferred languages from the browser, most preferred first
(`navigator.languages`), updated when the user changes them.

Renders `serverValue` on the server and during hydration, then switches to
the browser's list with no hydration mismatch.

Use when: picking a default locale, suggesting a translation, or formatting
with `Intl` in the user's language.
Don't use when: the server must render the right language on the first
response; read the `Accept-Language` header on the server instead, and pass
it as `serverValue` so the client agrees. Don't override a language the user
chose explicitly in your app.

@param serverValue - Languages on the server and during hydration. Default
`['en']`. Pass the parsed `Accept-Language` header if you have it, as a
constant or memoized array.

@example
const [language] = usePreferredLanguages()
const price = new Intl.NumberFormat(language, { style: 'currency', currency: 'EUR' }).format(9.99)

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/usePreferredLanguages.md

## usePrevious

```ts
import { usePrevious } from '@vincent.ri/react-tils'
function usePrevious<T>(value: T): T | undefined
```

The value `value` had before it last changed, or `undefined` until it first
changes. Re-renders that don't change `value` keep the same previous value,
so it answers "what was it before?", not "what was it last render?".

Kept in state, not read from a ref during render, so it's correct under
the React Compiler, Strict Mode, and concurrent rendering, where the common
ref version (`useRef` + `useEffect`) shows stale or skipped values.
Compares with `Object.is`, like React: a new object or array each render
counts as a change, so pass a primitive or a memoized value.

Use when: rendering from the change itself: a direction (price up or down,
slide left or right), "changed from X to Y", or animating from the old
value.
Don't use when: you want to run code when a value changes; do it in the
event handler that changes it, or in an effect with that value as a
dependency. For a prop to state copy, see `useControllableState`.

@param value - The value to follow.
@returns The value before the latest change, or `undefined` before any change.

@example
const previous = usePrevious(price)
const trend = previous === undefined ? '' : price > previous ? '▲' : price < previous ? '▼' : ''
return <span>{price} {trend}</span>

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/usePrevious.md

## useRovingFocus

```ts
import { useRovingFocus } from '@vincent.ri/react-tils'
function useRovingFocus<T extends HTMLElement = HTMLElement>(options?: RovingFocusOptions): (element: T | null) => void
```

Arrow-key navigation between the items of a toolbar, menu, tab list,
listbox, or radio group, with a single Tab stop (a "roving tabindex").
Returns a callback ref for the container.

Tab enters the group at the last focused item (or the selected one, else
the first) and Tab again leaves it. Arrow keys move between items, Home and
End jump to the ends, and typing letters jumps to the item whose text
starts with them. Left and Right swap in right-to-left content.
Disabled and hidden items are skipped. Items added later are included.

Use when: a custom toolbar, menu, tab list, listbox, or segmented control.
Don't use when: native elements do it: radio buttons with the same `name`,
and `<select>`. Don't set `tabIndex` on the items yourself; the hook manages
it. Still add the ARIA roles (`role="toolbar"`, `role="tab"`, …) for screen
readers. Two-dimensional grids need more than this.

Other libraries call this `useRovingTabIndex`.

@param options - `orientation`, `loop`, `typeahead`, `selector`. Optional.
@returns A callback ref. Pass it to the container's `ref` prop.

@example
const ref = useRovingFocus<HTMLDivElement>({ orientation: 'horizontal' })
return (
  <div ref={ref} role="toolbar" aria-label="Formatting">
    <button>Bold</button>
    <button>Italic</button>
    <button>Underline</button>
  </div>
)

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useRovingFocus.md

## useScript

```ts
import { useScript } from '@vincent.ri/react-tils'
function useScript(src: string, options?: ScriptOptions): ScriptStatus
```

Loads an external script once and reports its status: `'idle'`,
`'loading'`, `'ready'`, or `'error'`.

Every component using the same `src` shares one `<script>` tag and one
status. The tag is added on mount (never on the server) and is not removed
on unmount, because a script that has run cannot be unloaded. Status is
`'idle'` on the server, during hydration, and while disabled.

Use when: a third-party SDK has no npm package or must load from its own
domain, e.g. Stripe.js, Google Maps, or a chat widget.
Don't use when: an npm package exists; import it, and use `import()` to load
it lazily. In Next.js, `next/script` also handles loading strategies. A
failed load stays `'error'` for that `src`; to retry, change the `src`.

Other libraries call this `useExternal`.

@param src - Script URL.
@param options - `enabled` and `attributes`. Optional.

@example
const status = useScript('https://js.stripe.com/v3/', { attributes: { nonce } })
if (status === 'error') return <p>Payments are unavailable right now.</p>
if (status !== 'ready') return <Spinner />
return <Checkout stripe={window.Stripe(publishableKey)} />

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useScript.md

## useScrollDirection

```ts
import { useScrollDirection } from '@vincent.ri/react-tils'
function useScrollDirection(threshold?: number): ScrollDirection
```

The direction the page last scrolled: `'up'` or `'down'`.

Re-renders only when the direction flips, not on every scroll event.
Movements smaller than `threshold` pixels are ignored, so small jitters
(trackpad bounce, iOS overscroll) don't flip it. Always `'up'` at the top of
the page, on the server, and during hydration.

Use when: hiding a header while scrolling down and showing it when scrolling
up, or showing a "back to top" button only while scrolling up.
Don't use when: you need the position itself; use `useWindowScroll`. For a
header that just sticks, use CSS `position: sticky`.

@param threshold - Ignore movements smaller than this, in pixels. Default `10`.

@example
const direction = useScrollDirection()
return <header className={direction === 'down' ? 'header hidden' : 'header'}>…</header>

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useScrollDirection.md

## useScrollLock

```ts
import { useScrollLock } from '@vincent.ri/react-tils'
function useScrollLock(locked?: boolean): void
```

Stops the page from scrolling while `locked` is `true`, e.g. behind a modal.

Sets `overflow: hidden` on `<body>` and pads it by the scrollbar width so the
layout does not shift. Locks are counted, so nested modals work: the page
unlocks when the last one releases. Restores the original styles. Applied in
a layout effect, so there is no frame where the page can scroll.

Use when: a modal, drawer, or full-screen menu is open.
Don't use when: you use the native `<dialog>` with `showModal()`, where CSS
`body:has(dialog[open]) { overflow: hidden }` is enough. To lock scrolling
inside an element, use CSS `overscroll-behavior: contain`.

Other libraries call this `useLockBodyScroll`.

@param locked - Lock while `true`. Default `true`.

@example
function Modal({ open, children }: { open: boolean; children: React.ReactNode }) {
  useScrollLock(open)
  return open ? <div role="dialog" aria-modal="true">{children}</div> : null
}

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useScrollLock.md

## useScrollProgress

```ts
import { useScrollProgress } from '@vincent.ri/react-tils'
function useScrollProgress<T extends Element = HTMLElement>(): [(element: T | null) => void, number]
```

How far the user has scrolled through an element, from `0` (its top at the
top of the viewport) to `1` (its bottom at the bottom of the viewport).
Returns a callback ref for the element.

Updates on page scroll, window resize, and when the element's own size
changes (images loading, content added). An element shorter than the
viewport counts as read once it is fully visible. `0` on the server and
until the element is measured.

Use when: a reading-progress bar for an article or docs page, or showing
how much of a long form or terms text is left. For the whole page, put the
ref on the element that wraps its content (`<main>`).
Don't use when: the content scrolls inside a container, not the page; use
`useElementScroll`. For purely visual effects, CSS scroll-driven animations
avoid re-renders where supported.

Other libraries call this `useReadingProgress`, `useScrollPercentage`.

@returns `[ref, progress]`, with `progress` from `0` to `1`.

@example
const [ref, progress] = useScrollProgress<HTMLElement>()
return (
  <>
    <div className="progress-bar" style={{ transform: `scaleX(${progress})` }} />
    <article ref={ref}>…</article>
  </>
)

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useScrollProgress.md

## useScrollSpy

```ts
import { useScrollSpy } from '@vincent.ri/react-tils'
function useScrollSpy(ids: readonly string[], options?: ScrollSpyOptions): string | null
```

The id of the section the user is reading: the last of `ids` whose element
has scrolled past the top of the viewport (plus `offset`). At the bottom of
the page the last section is active, even if it is too short to reach the
top. `null` before the first section, on the server, and during hydration.

Re-renders only when the active section changes. Sections are looked up by
id on each scroll, so they can mount later.

Use when: highlighting the current section in a table of contents, a docs
sidebar, or step navigation on a long page.
Don't use when: the sections scroll inside a container rather than the page;
this follows the window. To know whether one element is on screen, use
`useInView`.

Other libraries call this `useActiveSection`, `useScrollspy`.

@param ids - Element ids of the sections, in page order.
@param options - `offset`: height of a sticky header in pixels. Optional.
@returns The active id, or `null`.

@example
const ids = ['install', 'usage', 'api']
const active = useScrollSpy(ids, { offset: 64 })
return (
  <nav>
    {ids.map((id) => (
      <a key={id} href={`#${id}`} aria-current={active === id ? 'location' : undefined}>{id}</a>
    ))}
  </nav>
)

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useScrollSpy.md

## useSearchParam

```ts
import { useSearchParam } from '@vincent.ri/react-tils'
function useSearchParam(name: string, serverValue?: string | null): [string | null, (value: string | null, options?: {
  push?: boolean
```

One URL query parameter (`?tab=billing`) as state: its value, or `null`
when it's missing, and a setter that updates the URL without reloading.
Works with or without a router: re-renders on `set` (in any component),
Back and Forward, and router navigation that uses `history.pushState` (in
browsers with the Navigation API).

The server render and hydration use `serverValue`, then the real URL with
no hydration mismatch. Pass the request's value (e.g. from `searchParams`
in a Next.js page) so the first frame is already right.

Works with Next.js's App Router: after `set`, Next's own `useSearchParams`
updates too, and no server request is made.

Use when: state that should be linkable, bookmarkable, and survive reload:
the selected tab, a search query, filters, sorting, a page number, an open
item's id.
Don't use when: your router already gives you this (React Router's
`useSearchParams`); for state that shouldn't reach the server, use `useHash`;
for private or large state, use `useLocalStorage`. Values are strings: parse
numbers and validate, since anyone can edit the URL.

Other libraries call this `useQueryState` (nuqs), `useSearchParam` (react-use), `useUrlState`.

@param name - The parameter name.
@param serverValue - The value on the server and during hydration. Default `null`.
@returns `[value, set]`. `set(value)` replaces the current history entry;
`set(value, { push: true })` adds one, so Back undoes it. `set(null)` removes the parameter.

@example
const [query, setQuery] = useSearchParam('q')
return <input value={query ?? ''} onChange={(e) => setQuery(e.target.value || null)} />

// Tabs where Back returns to the previous tab
const [tab, setTab] = useSearchParam('tab')
return <button onClick={() => setTab('billing', { push: true })}>Billing</button>

Browser support: all modern browsers. Router navigation that changes the URL with `history.pushState` (e.g. Next.js `<Link>`) is noticed only where the Navigation API exists. Elsewhere the value still updates on Back and Forward and through the hook's own setter.

Docs: https://vincentri.github.io/react-tils/hooks/useSearchParam.md

## useServiceWorkerUpdate

```ts
import { useServiceWorkerUpdate } from '@vincent.ri/react-tils'
function useServiceWorkerUpdate(options?: ServiceWorkerUpdateOptions): {
  updateAvailable: boolean
```

Whether a new version of your service worker (a PWA's offline code) is
installed and waiting, and `update()` to switch to it and reload once.

Notices a worker that was already waiting when the page loaded, and one
that finishes installing while the page is open. `update()` tells the
waiting worker to take over, then reloads the page exactly once when it
has, never in a loop. Nothing happens on the server or without a service
worker.

Your service worker must call `self.skipWaiting()` when it receives the
message `{ type: 'SKIP_WAITING' }`. Workbox and vite-plugin-pwa do this
with their "prompt for update" setting.

Use when: showing a "New version available. Reload" banner in a PWA or
any site with a service worker.
Don't use when: you don't use a service worker; a deploy then reaches
users on their next page load anyway. To check whether the user is
online, use `useOnline`.

Other libraries call this `useRegisterSW` (vite-plugin-pwa), `useServiceWorker`.

@param options - `checkIntervalMs`. Optional.
@returns `{ updateAvailable, update }`.

@example
const { updateAvailable, update } = useServiceWorkerUpdate({ checkIntervalMs: 60 * 60_000 })
if (!updateAvailable) return null
return (
  <div role="status">
    A new version is available. <button onClick={update}>Reload</button>
  </div>
)

Browser support: all modern browsers. Service workers need a secure page (HTTPS or localhost).

Docs: https://vincentri.github.io/react-tils/hooks/useServiceWorkerUpdate.md

## useSessionStorage

```ts
import { useSessionStorage } from '@vincent.ri/react-tils'
function useSessionStorage<T>(key: string, serverValue: T): [T, SetValue<T>]
```

State that persists in `sessionStorage` as JSON for the life of the tab,
stays in sync across components, and is safe to server-render.

Renders `serverValue` on the server and during hydration, then switches to the
stored value with no hydration mismatch. Missing or unparseable stored values
also read as `serverValue`. Setting `undefined` removes the key.

Values go through JSON: a `Date` comes back as a string, and `Map`, `Set`,
`Infinity`, and `undefined` inside objects don't survive. Store plain data.
Writes made directly with `sessionStorage` in the same tab aren't seen; go
through the setter.

Use when: state should survive a reload but not outlive the tab, and each tab
keeps its own copy (multi-step form progress, scroll restore, a dismissed
banner for this visit).
Don't use when: the state should be shared between tabs or survive closing
the tab; use `useLocalStorage`. Same limits as localStorage: no sensitive
data (any script on the page can read it), no large data.

Other libraries call this `useSessionStorageState`.

@param key - The sessionStorage key.
@param serverValue - Value on the server, during hydration, and when nothing
valid is stored. Pass a primitive or a constant, so the setter stays stable.
@returns `[value, setValue]`, like `useState`. `setValue` accepts a value or
an updater. If storage is full or blocked, the value still updates for this
page session but isn't saved.

@example
const [step, setStep] = useSessionStorage('checkout-step', 1)
setStep((s) => s + 1)

const [dismissed, setDismissed] = useSessionStorage('promo-dismissed', false)

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useSessionStorage.md

## useShare

```ts
import { useShare } from '@vincent.ri/react-tils'
function useShare(): {
  supported: boolean
```

Opens the device's native share sheet (Web Share API), and says whether it
is available.

`supported` is `false` on the server and during hydration, so a share button
appears after hydration with no mismatch. `share` resolves `true` when
shared, and `false` when unsupported, when the data can't be shared (e.g.
files on a browser that doesn't support them), or when the user cancels.

Use when: a "Share" button on mobile, especially for links or files.
Don't use when: you need a fallback everywhere; desktop Firefox and many
desktop setups don't support it, so pair it with `useCopyToClipboard`. Call
`share` from a user action (click); browsers refuse otherwise.

@returns `{ supported, share }`.

@example
const { supported, share } = useShare()
const [copy, copied] = useCopyToClipboard()
return supported ? (
  <button onClick={() => share({ title: post.title, url: post.url })}>Share</button>
) : (
  <button onClick={() => copy(post.url)}>{copied ? 'Copied!' : 'Copy link'}</button>
)

Browser support: not available in Firefox. Where `navigator.share` is missing, `supported` is `false` and `share` resolves to `false`; offer `useCopyToClipboard` instead.

Docs: https://vincentri.github.io/react-tils/hooks/useShare.md

## useSpeechRecognition

```ts
import { useSpeechRecognition } from '@vincent.ri/react-tils'
function useSpeechRecognition(options?: SpeechRecognitionOptions): SpeechRecognitionState
```

Turns speech from the microphone into text with the browser's built-in
speech recognition: the final transcript, the words still being
recognized, and whether it is listening.

Works in Chrome, Edge, and Safari; `supported` is `false` in Firefox.
Chrome sends the audio to Google's servers to recognize it, so it needs a
connection. Recognition stops by itself after a pause unless `continuous`
is set, and always on unmount.

Use when: dictation into a search box, chat input, or note, as an
optional extra next to typing.
Don't use when: you need it in every browser, offline, or with consistent
accuracy; record audio with `useMediaRecorder` and send it to a
transcription API. Don't make it the only way to enter text.

Other libraries call this `useSpeechToText`, `react-speech-recognition`, `useVoice`.

@param options - `lang`, `continuous`. Optional.
@returns `{ supported, listening, transcript, interim, error, start, stop, reset }`.

@example
const speech = useSpeechRecognition({ lang: 'en-US' })
useEffect(() => {
  if (speech.transcript) setQuery(speech.transcript)
}, [speech.transcript])
if (!speech.supported) return null
return (
  <button onClick={speech.listening ? speech.stop : speech.start}>
    {speech.listening ? 'Stop' : '🎤 Dictate'}
  </button>
)

Browser support: not available in Firefox. Uses `SpeechRecognition` or its `webkit` prefixed version. Where neither exists (Firefox), `supported` is `false` and `start` does nothing.

Docs: https://vincentri.github.io/react-tils/hooks/useSpeechRecognition.md

## useSpeechSynthesis

```ts
import { useSpeechSynthesis } from '@vincent.ri/react-tils'
function useSpeechSynthesis(): SpeechSynthesisState
```

Reads text aloud with the browser's speech synthesis, with the voice list
and whether it is speaking.

Handles the browser quirks: voices load after the page (the list is empty
at first and fills in with a re-render), Chrome stops long text after about
15 seconds (text is read in sentence-sized parts), and Chrome can garbage
collect an utterance mid-sentence so its end never fires (they are kept
until done). Stops on unmount.

Use when: a "Read aloud" button for AI answers, articles, or lessons, or
spoken feedback in a hands-free flow.
Don't use when: you need natural, consistent voices across devices;
generate audio with a text-to-speech API and play it. Voices differ by
browser and operating system.

Other libraries call this `useSpeech`, `useTextToSpeech`, `react-speech-kit`.

@returns `{ supported, voices, speaking, speak, cancel }`.

@example
const { supported, speaking, speak, cancel } = useSpeechSynthesis()
if (!supported) return null
return speaking
  ? <button onClick={cancel}>Stop</button>
  : <button onClick={() => speak(answer, { rate: 1.1 })}>Read aloud</button>

Browser support: all modern browsers. Where the API is missing, `supported` is `false`. The voices on offer depend on the browser and operating system.

Docs: https://vincentri.github.io/react-tils/hooks/useSpeechSynthesis.md

## useStickToBottom

```ts
import { useStickToBottom } from '@vincent.ri/react-tils'
function useStickToBottom<T extends HTMLElement = HTMLElement>(): [(element: T | null) => void, StickToBottom]
```

Keeps a scrollable element scrolled to the bottom as content is added or
grows, like a chat or a log, until the user scrolls up to read. Scrolling
back to the bottom, or calling `scrollToBottom`, follows again.

Follows content that grows with no scroll event, such as an AI reply
streamed into the last message. Starts at the bottom. Only scrolling up
stops following (wheel, touch, keys, or scrollbar), and it stops as soon as
the user starts, so it never cancels their scroll. Its own scrolling never
counts as the user's.

Use when: a chat, AI chat, terminal output, or live log.
Don't use when: new items appear at the top (a feed). Loading older
messages above doesn't need it either, but Safari has no scroll anchoring,
so there the view jumps unless you restore the position yourself: after
prepending, add the change in `scrollHeight` to `scrollTop`. For only reading the scroll position, use
`useElementScroll`.

Other libraries call this `useAutoScroll`, `useChatScroll`.

@returns `[ref, { atBottom, scrollToBottom }]`. Pass `ref` to the scrollable
element (with `overflow: auto` and a fixed or max height).

@example
const [ref, { atBottom, scrollToBottom }] = useStickToBottom<HTMLDivElement>()
return (
  <>
    <div ref={ref} style={{ overflowY: 'auto', height: 500 }}>
      {messages.map((m) => <Message key={m.id} {...m} />)}
    </div>
    {!atBottom && <button onClick={() => scrollToBottom()}>Jump to latest</button>}
  </>
)

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useStickToBottom.md

## useSwipe

```ts
import { useSwipe } from '@vincent.ri/react-tils'
function useSwipe<T extends HTMLElement = HTMLElement>(onSwipe: (direction: SwipeDirection, event: PointerEvent) => void, options?: SwipeOptions): (element: T | null) => void
```

Calls `onSwipe` with `'left'`, `'right'`, `'up'`, or `'down'` when the user
swipes on an element, with touch, pen, or mouse. Returns a callback ref.

Uses pointer events, so one handler covers every input. The direction is the
axis that moved most. Too short or too slow and it isn't a swipe.

Use when: swiping between carousel slides, dismissing a card or
notification, or closing a drawer with a swipe.
Don't use when: you need the element to follow the finger while dragging;
use `useDrag`. For scrolling between items,
CSS scroll snap (`scroll-snap-type`) needs no JS. Swipes must have a button
or keyboard alternative.

Set CSS `touch-action` on the element so the browser doesn't take the
gesture for scrolling: `pan-y` for horizontal swipes, `pan-x` for vertical,
`none` for both.

@param onSwipe - Called with the direction and the `pointerup` event. Can change every render.
@param options - `threshold` and `maxDurationMs`. Optional.
@returns A callback ref. Pass it to the element's `ref` prop.

@example
const ref = useSwipe<HTMLDivElement>((direction) => {
  if (direction === 'left') next()
  if (direction === 'right') previous()
})
return <div ref={ref} style={{ touchAction: 'pan-y' }}><Slide /></div>

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useSwipe.md

## useTextSelection

```ts
import { useTextSelection } from '@vincent.ri/react-tils'
function useTextSelection<T extends Element = HTMLElement>(): [(element: T | null) => void, TextSelection | null]
```

The text the user has selected inside an element, or `null`. Returns a
callback ref for the element.

Follows mouse, touch, and keyboard selection (Shift+arrows, select all).
While the mouse or finger is still down it waits, so a toolbar doesn't
flicker during a drag, and updates on release. `null` when the selection is
empty, only whitespace, or not entirely inside the element.

Use when: a floating toolbar for highlight, comment, share quote, or "Ask AI
about this", or a "copy quote" button.
Don't use when: the text is in an `<input>` or `<textarea>`; read its
`selectionStart` and `selectionEnd`. For a rich text editor, use the
editor's own selection API. `rect` doesn't follow scrolling; read
`range.getBoundingClientRect()` again if the page scrolls.

@returns `[ref, selection]`. Pass `ref` to the element containing the text.

@example
const [ref, selection] = useTextSelection<HTMLElement>()
return (
  <>
    <article ref={ref}>{children}</article>
    {selection && (
      <div style={{ position: 'fixed', top: selection.rect.top - 40, left: selection.rect.left }}>
        <button onClick={() => quote(selection.text)}>Quote</button>
      </div>
    )}
  </>
)

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useTextSelection.md

## useThrottledCallback

```ts
import { useThrottledCallback } from '@vincent.ri/react-tils'
function useThrottledCallback<A extends unknown[]>(callback: (...args: A) => void, intervalMs: number): ThrottledFunction<A>
```

Returns a throttled version of `callback`: it runs right away, then at most
once every `intervalMs` while calls keep coming, and once more at the end
with the arguments of the last call, so the final value is never lost. The
returned function is stable and always runs the latest `callback`.

A pending call is dropped on unmount (call `flush` first to keep it) and
when `intervalMs` changes.

Use when: work that should keep happening during a burst, not only after
it: live search results while typing, saving a slider's position, sending
"typing…" or cursor positions to a server, analytics for scroll depth.
Don't use when: it should run once after the user stops (autosave a draft,
validate); use `useDebouncedCallback`. To follow scroll or size, use
`useWindowScroll`, `useElementScroll`, or `useElementSize`, which already
avoid extra re-renders. For drawing on every frame, use `useAnimationFrame`.

Other libraries call this `useThrottleFn`, `useThrottleCallback`, `useThrottle`.

@param callback - The function to throttle. Can change every render.
@param intervalMs - Run at most once per this many milliseconds.
@returns The throttled function, with `cancel`, `flush`, and `pending`.

@example
const sendCursor = useThrottledCallback((x: number, y: number) => socket.send({ x, y }), 100)
return <div onPointerMove={(e) => sendCursor(e.clientX, e.clientY)} />

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useThrottledCallback.md

## useTimeout

```ts
import { useTimeout } from '@vincent.ri/react-tils'
function useTimeout(callback: () => void, delayMs: number | null): () => void
```

Calls `callback` once, `delayMs` after mount or after `delayMs` changes.
Pass `null` to cancel. Always calls the latest `callback`. Cleared on
unmount. Nothing runs on the server.

Returns `restart`, which starts the delay over: for a "Saved ✓" label that
should stay for 2s after the latest save, not the first one.

Use when: auto-dismissing a toast, hiding a "Saved" or "Copied" label, or a
delay before showing a spinner. Pause a toast on hover by passing `null`.
Don't use when: it should repeat; use `useInterval`. To wait until the user
stops typing, use `useDebouncedCallback` or `useDebouncedValue`. For "Copied!"
after copying, `useCopyToClipboard` already resets itself.

Other libraries call this `useTimeoutFn`.

@param callback - Called when the delay ends. Can change every render.
@param delayMs - Milliseconds to wait, or `null` to cancel.
@returns `restart`: start the delay over. Does nothing while `delayMs` is `null`.

@example
function Toast({ onClose }: { onClose: () => void }) {
  const [hovered, setHovered] = useState(false)
  useTimeout(onClose, hovered ? null : 5000)
  return <div onPointerEnter={() => setHovered(true)} onPointerLeave={() => setHovered(false)}>Saved</div>
}

// Show "Saved" for 2s after the latest save.
const [saved, setSaved] = useState(false)
const restart = useTimeout(() => setSaved(false), 2000)
const onSave = () => { setSaved(true); restart() }

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useTimeout.md

## useUserMedia

```ts
import { useUserMedia } from '@vincent.ri/react-tils'
function useUserMedia(constraints: MediaStreamConstraints, options?: {
  enabled?: boolean
```

Opens the camera and/or microphone with `getUserMedia`, and stops every
track on unmount, when disabled, or when the constraints change, so the
camera light turns off.

Enabling it makes the browser ask for permission the first time. Returns
`{ stream: null, loading: false }` on the server, during hydration, and while
disabled. Constraints are compared by value, so an inline object is fine.

Use when: a video call preview, scanning a QR code, recording audio, or
taking a profile photo.
Don't use when: a file input is enough (`<input type="file"
accept="image/*" capture>` opens the camera on phones with no permission
prompt). To check the permission first, use `usePermission('camera')`.

@param constraints - `getUserMedia` constraints, e.g. `{ video: true, audio: false }`.
@param options - `enabled`: request while `true`. Default `true`.

@example
const { stream, error } = useUserMedia({ video: { facingMode: 'environment' } })
const videoRef = useCallback(
  (video: HTMLVideoElement | null) => {
    if (video) video.srcObject = stream
  },
  [stream],
)
if (error) return <p>Camera unavailable: {error.message}</p>
return <video ref={videoRef} autoPlay playsInline muted />

Browser support: all modern browsers. Needs a secure page (HTTPS or localhost).

Docs: https://vincentri.github.io/react-tils/hooks/useUserMedia.md

## useVisualViewport

```ts
import { useVisualViewport } from '@vincent.ri/react-tils'
function useVisualViewport(serverValue?: VisualViewportState): VisualViewportState
```

The visual viewport: the part of the page actually visible, which shrinks
when the on-screen keyboard opens on phones and moves with pinch zoom.

`bottomInset` is how many pixels at the bottom of the layout viewport are
covered, so a fixed bottom bar can move above the keyboard. Renders
`serverValue` on the server and during hydration. Falls back to the window
size where `visualViewport` is missing.

Use when: keeping a chat input, bottom toolbar, or "Save" bar visible above
the mobile keyboard, or positioning UI correctly while pinch-zoomed.
Don't use when: you just need the window size; use `useWindowSize`. Where
supported, CSS can handle the keyboard: the
`interactive-widget=resizes-content` viewport meta setting, or
`env(keyboard-inset-height)` with the VirtualKeyboard API.

@param serverValue - Value on the server and during hydration. Default all zeros, scale `1`.

@example
const { bottomInset } = useVisualViewport()
return <form style={{ position: 'fixed', left: 0, right: 0, bottom: bottomInset }}><ChatInput /></form>

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useVisualViewport.md

## useWakeLock

```ts
import { useWakeLock } from '@vincent.ri/react-tils'
function useWakeLock(enabled?: boolean): {
  supported: boolean
```

Keeps the screen from dimming or locking while `enabled` is `true`, using
the Screen Wake Lock API.

The browser releases the lock whenever the tab is hidden; this hook
re-acquires it when the tab is visible again. Released on unmount or when
disabled. `supported` and `active` are `false` on the server and during
hydration. Unsupported browsers or refused requests (e.g. low battery) just
leave `active` as `false`.

Use when: the user reads or follows along without touching the screen, e.g.
a recipe, a presentation, a timer, turn-by-turn directions, or a QR code
ticket.
Don't use when: video is playing; browsers already keep the screen on. Don't
enable it for the whole app: it drains the battery. Turn it on for the
screen that needs it.

@param enabled - Keep the screen awake while `true`. Default `true`.
@returns `{ supported, active }`.

@example
const [cooking, setCooking] = useState(false)
const { supported } = useWakeLock(cooking)
return supported ? <Toggle checked={cooking} onChange={setCooking}>Keep screen on</Toggle> : null

Browser support: all modern browsers. Where the API is missing, `supported` is `false` and the screen follows the device's normal sleep settings.

Docs: https://vincentri.github.io/react-tils/hooks/useWakeLock.md

## useWindowFocus

```ts
import { useWindowFocus } from '@vincent.ri/react-tils'
function useWindowFocus(serverValue?: boolean): boolean
```

Whether the browser window has focus, updated on focus and blur.

Renders `serverValue` on the server and during hydration, then switches to
`document.hasFocus()` with no hydration mismatch.

Use when: the page is visible but the user is in another window, e.g. pause
a game, mark messages as read only while focused, or refetch on return.
Don't use when: you mean "the tab is hidden"; use `useDocumentVisibility`
(a visible page can be unfocused, e.g. side by side with another window).
For focus inside the page (which input is active), use `focus`/`blur`
handlers or CSS `:focus-within`.

@param serverValue - Value on the server and during hydration. Default `true`.

@example
const focused = useWindowFocus()
useEffect(() => {
  if (focused) markAsRead(conversationId)
}, [focused, conversationId])

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useWindowFocus.md

## useWindowScroll

```ts
import { useWindowScroll } from '@vincent.ri/react-tils'
function useWindowScroll(serverValue?: WindowScroll): WindowScroll
```

The window's scroll position in CSS pixels, updated on scroll.

Renders `serverValue` on the server and during hydration, then switches to the
real position with no hydration mismatch. Re-renders on every scroll event
that moves the page (not throttled).

Use when: JS needs the scroll position, e.g. a "back to top" button after
scrolling down, or parallax that depends on the exact offset.
Don't use when: you only need to know if an element is visible; use
`useInView`, which does not re-render on every scroll. For a header that
hides on scroll down, use `useScrollDirection`; for a reading progress bar,
`useScrollProgress`; both re-render far less. For sticky
elements, use CSS `position: sticky`. For scroll-linked animation, use CSS
scroll-driven animations.

@param serverValue - Position on the server and during hydration. Default
`{ x: 0, y: 0 }`. Pass a constant, not an inline object.

@example
const { y } = useWindowScroll()
return y > 400 ? <button onClick={() => window.scrollTo({ top: 0 })}>Top</button> : null

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useWindowScroll.md

## useWindowSize

```ts
import { useWindowSize } from '@vincent.ri/react-tils'
function useWindowSize(serverValue?: WindowSize): WindowSize
```

The window's inner width and height in CSS pixels, updated on resize. Like
`window.innerWidth`, the width includes a visible vertical scrollbar; for the
width without it, read `document.documentElement.clientWidth` or use
`useElementSize` on a full-width element.

Renders `serverValue` on the server and during hydration, then switches to the
real size with no hydration mismatch. Re-renders only when the size actually
changes, on every resize event that changes it (not throttled).

Use when: JS needs exact pixel values, e.g. canvas sizing, virtualized lists,
or positioning a popover inside the viewport.
Don't use when: you only need a breakpoint; use `useMediaQuery`, which
re-renders only when the breakpoint flips. For styling, use CSS. For an
element's size, use CSS container queries or `useElementSize`.

@param serverValue - Size on the server and during hydration. Default
`{ width: 0, height: 0 }`. Pass a constant, not an inline object.

@example
const { width, height } = useWindowSize()
return <canvas width={width} height={height} />

Browser support: all modern browsers.

Docs: https://vincentri.github.io/react-tils/hooks/useWindowSize.md