@uniflowed/hooks

type

Async

export type Async<T> = {|
  readonly value: T | null,
  readonly error: Error | null,
  readonly pending: boolean,
  /** Run it again, keeping whatever is on screen until the new value lands. */
  readonly reload: () => void,
|};

What an in-flight, settled or failed call looks like.

type

AsyncOptions

export type AsyncOptions = {|
  /** How many times to try *again* after a failure. Zero, by default. */
  readonly retry?: number,
  /**
   * How long to wait before attempt `attempt` (counting from zero).
   *
   * Exponential with a ceiling, by default. A fixed delay is `() => 200`.
   */
  readonly retryDelay?: (attempt: number) => number,
|};

How hard to try.

hook

useAsync

export hook useAsync<T>(
  body: (signal: AbortSignal) => Promise<T>,
  deps: $ReadOnlyArray<mixed>,
  options?: AsyncOptions,
): Async<T> { ... }

Call body when deps change, and report what happened.

The previous value stays on screen while a reload is in flight, because blanking the page to show a spinner every time a filter changes is worse than showing slightly stale data for a moment. pending says which it is.

body is handed an AbortSignal that is aborted when the call is superseded — by a dependency change, a reload, or an unmount. Passing it to fetch is what makes a cancelled request actually stop; a body that ignores it is still correct, because the effect's own flag is what decides whether a result is written.

Nothing here runs during a prerender: useEffect does not run on a server, so a server-rendered page shows pending with no value, which is the same thing the client's first render shows. Data a page needs *in* its HTML belongs in a route loader, not in this hook.

type

BrowserNavigator

export type BrowserNavigator = {
  readonly onLine?: boolean,
  readonly userAgent?: string,
  readonly clipboard?: ?{
    readonly readText: () => Promise<string>,
    readonly writeText: (text: string) => Promise<void>,
    ...
  },
  readonly geolocation?: ?Geolocation,
  readonly permissions?: ?{
    readonly query: (descriptor: { readonly name: string, ... }) => Promise<PermissionStatus>,
    ...
  },
  readonly connection?: ?NetworkConnection,
  ...
};

The part of a navigator this package reads.

Not a declaration of Navigator — Flow ships one of those. This is the list of what these hooks actually touch, which is short enough to be worth writing down and is the reason none of them needs an any: everything below browserWindow() is checked against this.

Every field is optional because a hosted document is not required to carry the whole of a browser. navigator.geolocation is null under happy-dom and absent under a bare Node global, and navigator.connection exists nowhere but Chromium.

type

BrowserLocation

export type BrowserLocation = {
  readonly href: string,
  readonly hash: string,
  ...
};

The part of location this module reads.

href and the fragment, and nothing else. The path and the query are on the request, so @uniflowed/router has already resolved them and a second reading of them here would be a second answer to a settled question — see useHash.

type

BrowserHistory

export type BrowserHistory = {
  readonly state: mixed,
  readonly pushState: (state: mixed, unused: string, url: string) => void,
  readonly replaceState: (state: mixed, unused: string, url: string) => void,
  ...
};

The part of history this module writes through.

state is read so that a fragment written from here hands back whatever a router put there, rather than clearing it. The second parameter of both methods has been ignored by every browser since the API shipped, and is typed rather than omitted because it is positional.

type

BrowserNavigation

export type BrowserNavigation = {
  readonly addEventListener: (type: "currententrychange", listener: () => mixed) => void,
  readonly removeEventListener: (type: "currententrychange", listener: () => mixed) => void,
  ...
};

The part of the Navigation API this module listens to.

One event, and deliberately only one. currententrychange fires after the current history entry has changed *for any reason* — a link, the back button, and the two calls that fire nothing else, history.pushState and history.replaceState. It is the only thing the platform offers that hears a fragment written by code other than the writer, which is what makes useHash able to see @uniflowed/router's own navigation.

navigate and navigateerror are not here: intercepting a navigation is the router's business, and a hook that reads the fragment has no opinion about whether one should happen.

Optional on [BrowserWindow], because this is an addition rather than the base — see useHash for which browsers have it and what the others get.

type

NetworkConnection

export type NetworkConnection = {
  readonly downlink?: number,
  readonly effectiveType?: string,
  readonly saveData?: boolean,
  readonly addEventListener?: (type: string, listener: () => mixed) => void,
  readonly removeEventListener?: (type: string, listener: () => mixed) => void,
  ...
};

The Network Information object, which only Chromium has.

type

BrowserWindow

export type BrowserWindow = {
  readonly document: Document,
  readonly navigator: BrowserNavigator,
  readonly location?: ?BrowserLocation,
  readonly history?: ?BrowserHistory,
  readonly navigation?: ?BrowserNavigation,
  readonly localStorage?: ?Storage,
  readonly sessionStorage?: ?Storage,
  readonly innerWidth: number,
  readonly innerHeight: number,
  readonly scrollX: number,
  readonly scrollY: number,
  readonly matchMedia?: (query: string) => MediaQueryList,
  readonly getComputedStyle?: (element: Element) => CSSStyleDeclaration,
  readonly requestAnimationFrame?: (callback: (time: number) => mixed) => AnimationFrameID,
  readonly cancelAnimationFrame?: (handle: AnimationFrameID) => void,
  // Two overloads, the way Flow's own `EventTarget` is declared: a `storage`
  // listener is handed a `StorageEvent` and needs its `key`, and narrowing an
  // `Event` down to one at runtime would mean an `instanceof StorageEvent`
  // against a name that is not defined in every host a uf test runs in.
  readonly addEventListener: ((
    type: "storage",
    listener: (event: StorageEvent) => mixed,
    options?: EventListenerOptionsOrUseCapture,
  ) => void) &
    ((
      type: string,
      listener: (event: Event) => mixed,
      options?: EventListenerOptionsOrUseCapture,
    ) => void),
  readonly removeEventListener: ((
    type: "storage",
    listener: (event: StorageEvent) => mixed,
    options?: EventListenerOptionsOrUseCapture,
  ) => void) &
    ((
      type: string,
      listener: (event: Event) => mixed,
      options?: EventListenerOptionsOrUseCapture,
    ) => void),
  readonly ResizeObserver?: Class<ResizeObserver>,
  readonly IntersectionObserver?: Class<IntersectionObserver>,
  readonly MutationObserver?: Class<MutationObserver>,
  ...
};

The part of a window this package reads.

Same idea as [BrowserNavigator], and the same reason: naming what is touched turns every read in the package into a checked one. The observer constructors are optional because a browser old enough to lack one is a browser a hook here has to keep working in — it degrades to reporting nothing rather than throwing during a render.

function

browserWindow

export function browserWindow(): BrowserWindow | null { ... }

The window these hooks listen to, or null where there is no browser.

In a browser globalThis *is* the window, so globalThis.addEventListener looks correct. It is not correct anywhere a document has been installed onto another host's global — which is every uf test process, where globalThis is Node's and has no addEventListener at all. Ask the document's own window for its methods and both cases work.

Exported because it is the first question every hook in this package asks, and an application writing its own prerender-safe hook has to ask it too. The single ?? globalThis is this package's only unchecked step: window is any in Flow's own library definition, and this is where that stops.

hook

useSupported

export hook useSupported(probe: () => boolean): boolean { ... }

Whether a capability the browser may not have is there.

The naive version — typeof window.BroadcastChannel === "function" in the render — is a hydration mismatch waiting to happen: the server says one thing, the client's first render says another, and React reports it against whatever markup happened to differ. Asked through useSyncExternalStore, the server's answer is false, the hydrating render agrees with it, and React re-renders with the truth immediately afterwards.

probe is called during render, so it must only look — never install, never request. It is passed straight through rather than stabilised: a snapshot is a question the render is asking now, and a stable callback's body is installed in an insertion effect that has not run yet, so it would answer from the render before.

hook

useMediaQuery

export hook useMediaQuery(query: string, serverValue: boolean = false): boolean { ... }

Whether a media query matches.

serverValue is what a prerender should assume, and it has no honest default — a page that hides a sidebar under 48rem wants false on the server, and one that renders a mobile menu wants true. So the caller says.

hook

usePreferredColorScheme

export hook usePreferredColorScheme(serverValue: "light" | "dark" = "light"): "light" | "dark" { ... }

The reader's colour-scheme preference.

hook

usePrefersReducedMotion

export hook usePrefersReducedMotion(serverValue: boolean = false): boolean { ... }

Whether the reader has asked for less motion.

hook

useOnline

export hook useOnline(serverValue: boolean = true): boolean { ... }

Whether the browser thinks it is online.

hook

useDocumentVisible

export hook useDocumentVisible(serverValue: boolean = true): boolean { ... }

Whether the document is the one the reader is looking at.

hook

useHash

export hook useHash(): [
  string,
  (next: string, options?: {| readonly replace?: boolean |}) => void,
] { ... }

The fragment in the address bar, and a way to change it.

The one part of the URL that needs a hook. A request carries the path and the query, so a server render already knows both and @uniflowed/router's useRoute has resolved them; the fragment is never sent — the browser strips it before the request goes out — so there is no value for a server to know and no caller who could supply a better one. That is why this takes no serverValue where useMediaQuery and useOnline do: "" is not a default chosen for want of a better one, it is the only honest answer, and the client's hydrating render reports it too before re-rendering with the truth.

Returned without the #, and percent-decoded, so it compares directly against the id a section was given.

Writing does not scroll, and that is deliberate. Moving to a section and recording which tab is open are two intentions, and the platform couples them only because assigning location.hash is the old way to do both at once — so a tab strip that writes billing would jump the page. Call element.scrollIntoView() where scrolling is what was wanted.

replace overwrites the current history entry instead of adding one, which is what a tab strip wants: eleven tab clicks should not be eleven presses of the back button.

# What it hears, and where

history.pushState and history.replaceState fire no event of any kind — not hashchange, not popstate — so what a hook can see depends on where the write came from and on what the browser has:

| The write | Everywhere | Without the Navigation API | | --- | --- | --- | | the reader: an anchor, the address bar, back and forward | seen | seen | | this hook's own setter | seen | seen | | pushState from other code — @uniflowed/router's navigation | seen | **not seen** |

The first two are hashchange, popstate and the module's own registry. The third is currententrychange, which fires after the current history entry changes for any reason at all, and which is the only thing the platform offers that hears a write the writer did not announce.

"Without the Navigation API" is now a narrow set: Chrome and Edge have had it since 102 (2022), Safari since 26.2 and Firefox since 147 — but a reader on an older Safari or Firefox is a reader this column describes, and there the registry is still the whole answer. A router navigation that changes only the fragment leaves such a page showing the section it was on.

The fragment is deliberately not on RouteInfo — useRoute() cannot answer this question and should not learn to. A RouteInfo is what a *request* resolved to, and the browser strips the fragment before the request goes out, so a field for it would be one the server could never fill and the two renders would disagree about. This hook is the one answer, and currententrychange is what makes it a complete one on the browsers that have it rather than a second reading of a value the router also holds.

type

ScrollOffset

export type ScrollOffset = {| readonly x: number, readonly y: number |};

How far something has been scrolled.

Defined here rather than in dom.js because dom.js imports this module and not the other way round; useScroll over an element uses the same shape, and one name for one thing is worth the arrow.

type

Size

export type Size = {| readonly width: number, readonly height: number |};

How big something is. Shared with useElementSize for the same reason.

hook

useWindowSize

export hook useWindowSize(serverValue?: Size): Size { ... }

The size of the viewport.

hook

useWindowScroll

export hook useWindowScroll(serverValue?: ScrollOffset): ScrollOffset { ... }

How far the page has been scrolled.

The same packed-string snapshot as useWindowSize, for the same reason, and a passive listener because a scroll handler that could call preventDefault blocks scrolling on a touch screen until it has run.

hook

useScrollLock

export hook useScrollLock(locked: boolean): void { ... }

Hold the page still while locked.

A layout effect, so the page is frozen before the frame in which the dialog that asked for it appears — an ordinary effect lets one frame of scrolling through, which reads as a jump.

On a server this does nothing at all: effects do not run during a prerender, so a locked dialog rendered into HTML leaves the markup alone.

type

EffectiveConnectionType

export type EffectiveConnectionType = "slow-2g" | "2g" | "3g" | "4g";

How good the connection is, as the browser grades it.

type

NetworkMeasurement

export type NetworkMeasurement = {|
  /** Estimated bandwidth in megabits per second, where the browser reports it. */
  readonly downlink: number | null,
  readonly effectiveType: EffectiveConnectionType | null,
  /** Whether the reader has asked for less data to be used. */
  readonly saveData: boolean,
|};

What Network Information measured, where there is such a thing.

Its own type rather than three more fields on [Network], because the three of them arrive together or not at all: they come from navigator.connection, which is Chromium's alone. A server, and every other browser, has no object to read them off.

type

Network

export type Network = {|
  readonly online: boolean,
  readonly measured: NetworkMeasurement | null,
|};

What the browser will say about the connection.

measured used to be three flat fields and a supported boolean beside them, which is the shape this package now refuses: a caller had to read one field to learn whether three others meant anything, and downlink: null said both "this browser does not measure bandwidth" and "it does, and has not decided yet". A null here says one thing — nothing on this side can answer — and the fields that would have been guesses are not reachable to be read.

hook

useNetwork

export hook useNetwork(serverValue: boolean = true): Network { ... }

What the browser will say about the connection.

Only Chromium implements Network Information, so a browser that does not reports measured: null rather than three fields that are indistinguishable from a slow connection. online stays flat and is answered everywhere — it is the field almost every caller wants, and burying it behind a narrowing would have made the common case pay for the rare one.

The snapshot is a packed string for the reason useWindowSize gives: an object rebuilt on every check never compares equal, and useSyncExternalStore would re-render forever.

type

Geoposition

export type Geoposition = {|
  readonly latitude: number,
  readonly longitude: number,
  /** Radius of a 95% confidence circle, in metres. */
  readonly accuracy: number,
  readonly timestamp: number,
|};

Where the reader is, to the accuracy the browser was willing to give.

type

GeolocationReading

export type GeolocationReading =
  /**
   * Not watching, because the caller passed `enabled: false`. Reported before
   * `"unsupported"` is even considered, so it is the same on both sides of a
   * hydration.
   */
  | {| readonly status: "idle" |}
  /** No geolocation object here at all: a server render, or a browser without one. */
  | {| readonly status: "unsupported" |}
  /** Watching. The reader has been asked and has not answered yet. */
  | {| readonly status: "pending" |}
  /**
   * A fix. `error` is the failure of a *later* reading, and its presence means
   * the position beside it is the last good one rather than the current one.
   */
  | {| readonly status: "located", readonly position: Geoposition, readonly error: Error | null |}
  /** Refused, unavailable or timed out, with no earlier fix to fall back on. */
  | {| readonly status: "failed", readonly error: Error |};

What useGeolocation knows so far.

A union rather than a record of nullable fields, and the difference is the whole point of the type. The record it replaced — {| position: Geoposition | null, error: Error | null, supported: boolean |} — could represent eight states, of which four could never happen, and it asked every caller to work out from three fields which of the four real ones they were in. position == null meant "no browser", "not asked", "asked and refused" and "waiting for the reader to decide", and a page that wanted to say something different for each had to reconstruct the distinction the hook had thrown away.

Five states, each of which a page does something different about, and Flow refuses to read a field the state does not have.

hook

useGeolocation

export hook useGeolocation(options?: {|
  readonly enabled?: boolean,
  readonly highAccuracy?: boolean,
  readonly maximumAge?: number,
  readonly timeout?: number,
|}): GeolocationReading { ... }

Watch where the reader is.

An effect rather than a useSyncExternalStore, and the difference is not stylistic: there is no snapshot to read. The browser has no "current position" property to ask — the first value arrives in a callback, after a permission prompt the reader may take a minute to answer or never answer at all. So there is nothing but "unsupported" to report during a prerender and in the client's first render, which is also what makes it hydration-safe: the server writes the markup for a page that does not know where anybody is, and the hydrating render agrees with it.

Turning enabled off after a fix reports "idle" rather than keeping the position, because a reading nobody is watching is a reading nobody should be shown. A caller who wants the last one to stay on screen holds it.

Mounting this asks the reader for permission. Mount it on the page that needs a position, not at the top of an application.

type

PermissionName

export type PermissionName =
  | "geolocation"
  | "notifications"
  | "camera"
  | "microphone"
  | "clipboard-read"
  | "clipboard-write"
  | "persistent-storage"
  | "push"
  | "midi";

A permission this hook knows how to ask about.

type

PermissionAnswer

export type PermissionAnswer = "granted" | "denied" | "prompt" | "unknown";

What the browser says about a permission.

"unknown" is one value for four situations that a caller treats the same way — no Permissions API, a name this browser does not recognise, an answer that has not arrived yet, and a server render. Splitting them would make every caller write the same four-armed match to reach the same conclusion.

hook

usePermission

export hook usePermission(name: PermissionName): PermissionAnswer { ... }

Whether the reader has granted a permission, without asking for it.

Querying is not prompting: this reports the current state and follows it if the reader changes their mind in browser settings. Asking for the permission is the API's own job — getUserMedia, watchPosition — and doing it from here would make a hook that reads have a side effect nobody asked for.

An effect rather than a store, for the reason useGeolocation gives: the answer is a promise, so there is nothing to read synchronously.

type

UseBroadcastReturn

export type UseBroadcastReturn<T> = {|
  /** Send to every other page on this origin. Never to this one. */
  readonly post: (message: T) => void,
  readonly supported: boolean,
|};

What useBroadcast hands back.

hook

useBroadcast

export hook useBroadcast<T>(
  name: string,
  onMessage: (message: mixed) => mixed,
): UseBroadcastReturn<T> { ... }

Send and receive messages between the tabs of one origin.

A callback rather than a latest value, and that is the design decision in this file. A message is an event: it happened, it was worth acting on, and holding the most recent one as state invites a component to treat it as the truth — which it is not, because the tab that just opened has never received one and has no way to ask. Where two tabs need to agree about a *value*, useStorage is the hook: it has a snapshot every tab can read, and it already notifies across tabs.

A channel does not deliver to the page that posted. Two components in one tab sharing a channel therefore do not hear each other, which is the specification's behaviour and not this hook's.

T is what the caller promises to send. Nothing checks what arrives — it was serialised by another copy of the page, possibly an older deployment of it — so onMessage is handed mixed and validating it is the caller's, with @uniflowed/validator if it matters.

type

UseClipboardReturn

export type UseClipboardReturn = {|
  /** Put text on the clipboard. Resolves to whether it worked. */
  readonly copy: (text: string) => Promise<boolean>,
  /** Read the clipboard, which may prompt. `null` when it is refused. */
  readonly read: () => Promise<string | null>,
  /** True for `resetAfter` milliseconds following a successful copy. */
  readonly copied: boolean,
  readonly supported: boolean,
|};

What useClipboard hands back.

hook

useClipboard

export hook useClipboard(options?: {| readonly resetAfter?: number |}): UseClipboardReturn { ... }

The system clipboard.

copied exists because every copy button needs it: a tick that appears for a moment is the only feedback a copy has. It resets itself, and the timer is cleared at unmount, so a component that goes away during the pause does not set state afterwards.

Reading is a function rather than a value, deliberately. There is no event for "the clipboard changed", so a hook that exposed its contents as state would have to poll — and polling the clipboard means asking for permission repeatedly and reading whatever the reader copied out of their password manager. read() is called when the reader asks for a paste, which is when the browser expects to be asked.

document.execCommand("copy") is not used as a fallback. It is deprecated, it requires a hidden element and a selection, and the browsers that lack the asynchronous clipboard in 2026 are the ones that would not run this package anyway. supported says so instead of pretending.

type

Ref

export type Ref<T> = { current: T | null };

A ref object these hooks read: what useRef and useElementRef return.

type

ListenerTarget

export type ListenerTarget<T> = Ref<T> | (() => T | null) | null;

What a listener can be attached to.

A ref, or a function that finds the target. The function form is what covers the window and the document, which no ref points at.

type

ListenerOptions

export type ListenerOptions = {|
  readonly capture?: boolean,
  readonly passive?: boolean,
  readonly once?: boolean,
|};

The part of addEventListener's options a hook here passes on.

signal is deliberately absent: these hooks remove their own listener in the effect's cleanup, and a second, independent way to remove it would be a second thing that can be wrong.

hook

useEventListener

export hook useEventListener<TTarget extends EventTarget>(
  target: ListenerTarget<TTarget>,
  name: string,
  handler: (event: Event) => mixed,
  options?: ListenerOptions,
): void { ... }

Listen to an event on a target, cleaning up after itself.

The handler is stabilised, so passing an inline arrow does not tear the listener down and set it up again on every render — which is the bug this hook exists to prevent and the reason it does not take a dependency array.

The target is read once, when the listener is attached. Passing a ref and later pointing it at a different element does not move the listener; a component whose target changes should let the element unmount and mount again, which is what React does anyway when the element is conditional.

hook

useClickOutside

export hook useClickOutside(ref: Ref<HTMLElement>, handler: (event: Event) => mixed): void { ... }

Call handler when a press lands outside ref.

pointerdown rather than click, because a menu that closes on click stays open for the whole press — and because a click whose press started inside the menu and ended outside it should not close it.

hook

useHover

export hook useHover(ref: Ref<HTMLElement>): boolean { ... }

Whether the pointer is over the element.

hook

useFocusWithin

export hook useFocusWithin(ref: Ref<HTMLElement>): boolean { ... }

Whether focus is inside the element.

hook

useLongPress

export hook useLongPress(
  ref: Ref<HTMLElement>,
  handler: (event: Event) => mixed,
  options?: {| readonly delay?: number, readonly moveThreshold?: number |},
): void { ... }

Call handler when a press on the element lasts.

Cancelled by letting go, by the pointer leaving, and by the pointer moving further than moveThreshold — a press that turns into a scroll or a drag is not a long press, and a version that only watched for pointerup fires a context menu in the middle of a fling.

The handler is called once per press, while the finger is still down, which is when a long press is supposed to be felt.

hook

useElementSize

export hook useElementSize(ref: Ref<HTMLElement>): Size { ... }

The element's size, as the browser measures it.

A ResizeObserver rather than a window resize listener, because an element changes size when its content changes, when a sibling grows, and when a container query fires — none of which resizes the window.

hook

useIntersecting

export hook useIntersecting(
  ref: Ref<HTMLElement>,
  options?: {| readonly rootMargin?: string, readonly threshold?: number |},
): boolean { ... }

Whether the element is in the viewport.

type

MutationOptions

export type MutationOptions = {|
  /** Children added or removed. The default, unless another kind is asked for. */
  readonly childList?: boolean,
  /** Descendants as well as the element itself. */
  readonly subtree?: boolean,
  readonly attributes?: boolean,
  readonly characterData?: boolean,
  /** Only these attributes, where `attributes` is on. */
  readonly attributeFilter?: $ReadOnlyArray<string>,
|};

What part of the tree under the element to watch.

hook

useMutationObserver

export hook useMutationObserver(
  ref: Ref<HTMLElement>,
  handler: (records: $ReadOnlyArray<MutationRecord>) => mixed,
  options?: MutationOptions,
): void { ... }

Call handler when the element's markup changes.

The last resort of the three observers, and worth saying so: a size is a ResizeObserver, a position is an IntersectionObserver, and this is for the case where something outside React edits the DOM — a third-party widget, a browser extension, a contenteditable. Watching a tree React owns in order to learn about React's own updates is a mistake this hook cannot prevent but should not encourage.

attributeFilter is compared by its contents rather than its identity, so an array written inline in the call does not re-observe on every render.

hook

useScroll

export hook useScroll(ref: Ref<HTMLElement>): ScrollOffset { ... }

How far the element has been scrolled.

The element's own offset, not the page's — useWindowScroll is the page's, and lives in browser.js because there is only one page.

A passive listener, because a scroll handler that could call preventDefault blocks scrolling on a touch screen until it has run; and a layout effect for the first reading, because a container restored to a saved offset should not report zero for one frame.

hook

useElementRef

export hook useElementRef<T extends HTMLElement>(): Ref<T> { ... }

A ref for one of the hooks above, typed for the element you will attach it to.

hook

useElementState

export hook useElementState<T extends HTMLElement>(): [T | null, (node: T | null) => void] { ... }

The element a ref points at, as a value a render can depend on.

A ref is not state: React does not re-render when current changes, and reading ref.current during a render is a rule violation because the render that reads it may be one React throws away. A component that has to *render* something derived from its own element — a measurement, a portal target — needs the element as state, which is what a callback ref gives.

The returned function is stable, so passing it as ref={setNode} does not detach and reattach on every render.

type

EventStreamStatus

export type EventStreamStatus =
  /** Nothing has been attempted: a prerender, no URL, or `enabled: false`. */
  | "idle"
  /** Opening, or reopening — by the browser or by this hook. */
  | "connecting"
  /** Receiving. */
  | "open"
  /** Closed on purpose, by `close()`. It will not reopen on its own. */
  | "closed";

Where the connection is.

type

ServerEvent

export type ServerEvent = {|
  /** The `event:` name, or `message` where the stream sent none. */
  readonly name: string,
  /** The `data:` payload, as text. */
  readonly data: string,
  /** The `id:`, or `null`. */
  readonly id: string | null,
|};

One message, as the three fields the format carries.

type

EventSourceOptions

export type EventSourceOptions = {|
  /**
   * Named events to listen for, besides the unnamed `message`.
   *
   * A stream that sends `event: progress` delivers nothing to a `message`
   * listener, which is the single most common way an event stream appears to
   * be connected and silent.
   */
  readonly events?: $ReadOnlyArray<string>,
  /** Send cookies to another origin. Same-origin streams do not need it. */
  readonly withCredentials?: boolean,
  /** `false` closes the connection and opens none; `null` for the URL does too. */
  readonly enabled?: boolean,
  /** Called for every event, for a stream whose messages are events. */
  readonly onEvent?: (event: ServerEvent) => mixed,
  /** Milliseconds before this hook's first reopen; doubles. Default 1000. */
  readonly retryDelay?: number,
  /** The ceiling the doubling stops at. Default 30000. */
  readonly maxRetryDelay?: number,
|};

How the connection behaves.

type

UseEventSourceReturn

export type UseEventSourceReturn = {|
  readonly status: EventStreamStatus,
  /**
   * The most recent event, or `null` before one arrives.
   *
   * `./channels.js` deliberately does not hand back the last broadcast, and
   * the argument there is that a message is an event: a tab that just opened
   * has never received one and cannot ask. A stream is not that. It is a
   * connection with a lifetime, and for as long as it is open "the latest
   * message" is defined — which is what a progress bar, a price and a presence
   * indicator all are. `onEvent` is there for the streams that really are
   * events.
   */
  readonly last: ServerEvent | null,
  /**
   * The last `id:` seen, for a stream that resumes.
   *
   * The browser sends this itself when *it* reconnects. It is here for the
   * reconnection this hook makes, which cannot; see the module header.
   */
  readonly lastEventId: string | null,
  /** Close it. Nothing reopens until `enabled` or the URL changes. */
  readonly close: () => void,
  /** Whether this runtime has `EventSource` at all. */
  readonly supported: boolean,
|};

What useEventSource hands back.

hook

useEventSource

export hook useEventSource(url: string | null, options?: EventSourceOptions): UseEventSourceReturn { ... }

Subscribe to a server-sent event stream.

url is re-read when it changes, and a changed URL is a new connection — which is what makes the resume in the module header work at all. Pass null to connect to nothing, which is how a stream that depends on something not loaded yet waits without a second hook.

type

KeyComboOptions

export type KeyComboOptions = {|
  /** Listen on this element instead of the document. */
  readonly target?: Ref<HTMLElement> | null,
  /** Fire even while the reader is typing into a field. Off by default. */
  readonly whileTyping?: boolean,
  /** Fire again while the key is held down. Off by default. */
  readonly repeat?: boolean,
  /** Call `preventDefault` when it fires. On by default, since ⌘K is the browser's too. */
  readonly preventDefault?: boolean,
  /** Turn the binding off without changing where the hook is called. */
  readonly enabled?: boolean,
|};

How a chord is listened for.

hook

useKeyCombo

export hook useKeyCombo(
  combo: string,
  handler: (event: KeyboardEvent) => mixed,
  options?: KeyComboOptions,
): void { ... }

Call handler when a key combination is pressed.

useKeyCombo("mod+k", () => setSearchOpen(true));
useKeyCombo("escape", close, { whileTyping: true });

preventDefault defaults to on because the combinations worth binding are the ones the browser also wants — ⌘K is the address bar in Chrome, ⌘S is Save Page — and a shortcut that fires *and* opens a browser dialog is worse than either alone. A chord that is only the application's, like escape, loses nothing by it.

hook

useKeyHeld

export hook useKeyHeld(
  key: string,
  options?: {| readonly target?: Ref<HTMLElement> | null |},
): boolean { ... }

Whether a key is being held down.

For the case a chord cannot express: a modifier that changes what a drag does while it is held, a space bar that pans a canvas. key is matched against KeyboardEvent.key, case-insensitively, so "shift", "escape" and " " all work.

The blur reset is the reason this is a hook rather than two listeners. Holding a key and switching windows sends the keyup to the other window, so a hand-written version leaves the key held forever — the canvas stays panning after the reader comes back. Losing focus releases everything.

variable

useIsomorphicLayoutEffect

export const useIsomorphicLayoutEffect: typeof useLayoutEffect =
  typeof globalThis.document === "undefined" ? useEffect : useLayoutEffect;

useLayoutEffect in the browser, useEffect on the server.

uf prerenders every static route, and React warns that useLayoutEffect does nothing during a server render — correctly, because there is no layout to read. Every hook here that measures or subscribes uses this, so a hook is not a reason a page cannot be prerendered.

hook

useStableCallback

export hook useStableCallback<TArgs extends $ReadOnlyArray<mixed>, TReturn>(
  callback: (...args: TArgs) => TReturn,
): (...args: TArgs) => TReturn { ... }

A callback whose identity never changes and whose body is always the latest.

This is the useEvent shape from React's own RFC. The ref is written in an insertion effect rather than in the render, because writing it during render makes the callback's behaviour depend on whether that render was thrown away — and it is written before any layout effect runs, so a subscription set up in one already sees the current body.

hook

usePrevious

export hook usePrevious<T>(value: T): T | void { ... }

The value from the previous render, or undefined on the first.

hook

useMounted

export hook useMounted(): boolean { ... }

Whether the component has mounted.

For the case where a value differs between server and client and rendering the client's on the first pass would be a hydration mismatch: render the server's, then switch.

hook

useMount

export hook useMount(body: () => mixed): void { ... }

Run body once, after mount.

hook

useUnmount

export hook useUnmount(body: () => mixed): void { ... }

Run body once, at unmount.

hook

useRerender

export hook useRerender(): () => void { ... }

Force a re-render.

A counter rather than a boolean, because two renders in a row must both change the state or React drops the second.

type

RenderEnvelope

export type RenderEnvelope = {
  /** The instant the render was anchored to, in epoch milliseconds. */
  readonly at: number,
  /** The IANA zone the server was in. Not the reader's — see `Time`. */
  readonly timeZone: string,
  /** The seed both sides replay the same numbers from. */
  readonly seed: string,
};

What a render fixes, and what travels to the client.

variable

RENDER_META

export const RENDER_META: string = "uf:render";

The <meta> name the envelope is written under, and read back out of.

A name rather than an id because that is what a <meta> is addressed by: document.querySelector('meta[name=…]') is the read, and React's own hoisting treats the name/content pair as the element's identity.

component

RenderProvider

export component RenderProvider(
  at?: number,
  timeZone?: string,
  seed?: string,
  children: React.Node,
) { ... }

Fix this render's instant, zone and seed, and hand them to the tree.

A @uniflowed/router application already has one: routerView renders this above everything, so useRenderedAt and useRandom agree across hydration without the application saying anything. Rendering one by hand is for the cases that need different values, and it is a *replacement* rather than an addition — a nested provider inherits the envelope above it, overrides only the fields it was given, and writes no second carrier. See ubugeeei-prod/uf#559.

Every argument is optional and the defaults are the whole point: a server decides, the markup carries what it decided, and the browser reads it back before its first render, so neither side has to be told which one it is.

at and seed are there for the two cases that are not that. A test passes them to get a page that renders the same bytes every time; an application whose instant comes from somewhere better — a request header, a loader — passes that instead. Both have to be values the *browser* arrives at too: they are not carried, because what is carried is the outermost envelope, and a value only one side can compute is the mismatch this module exists to remove.

The carrier is a <meta>, which is what lets this be rendered above a root layout that owns <html>: React hoists it into the head of the document either way. The header of this file has the whole argument.

hook

useRenderEnvelope

export hook useRenderEnvelope(): RenderEnvelope | null { ... }

What this render was anchored to, or null outside a RenderProvider.

Null rather than a fabricated envelope, because "nobody fixed these values" is a fact the hooks in timing.js act on: without a provider they read the clock, which is the behaviour they have always had.

hook

useRenderedAt

export hook useRenderedAt(): Instant { ... }

The instant this page was rendered at, as a Temporal.Instant.

Constant for the life of the render, on both sides, which is what makes it safe to put in the markup. It is not "now" and does not become "now": a page left open for an hour still reports the instant it was rendered at, and a label that has to stay true while the reader looks at it is useTimeAgo.

Falls back to the clock outside a provider, which is right for a page that is only ever rendered once — and is a hydration mismatch on one that is prerendered, which is what the provider is for.

hook

useRenderTimeZone

export hook useRenderTimeZone(): string { ... }

The zone the render was made in.

The server's, not the reader's, and the distinction is the second half of the hydration problem rather than a detail: markup formatted in the reader's zone cannot match markup formatted in the server's, so a component renders this one and localises after hydration. @uniflowed/web's Time is that component.

hook

useRandom

export hook useRandom(label: string): Random { ... }

A stream of random numbers that both renders produce identically.

label names the stream, and naming it is what makes it independent of every other one: two components that ask for "featured" and "sidebar" get the same numbers whatever order they render in, and whatever suspends between them. Sharing one stream would make each component's numbers depend on how many the components above it happened to draw — stable in a synchronous render, and not stable once a boundary resolves at a different moment on the two sides.

The stream is stateful, so a component that draws from it during render draws different numbers on a re-render. Draw into a const keyed by what the numbers are for — which the React Compiler memoizes — or in an event, and never twice in the body of a component React may render twice.

Outside a provider the seed is a constant rather than the host's, which looks like the wrong default and is the right one: two renders with no envelope between them still have to agree, and a constant is the only seed both of them can arrive at. What it costs is that every such page shuffles the same way, which is a reason to render a provider rather than a reason to be unpredictable here.

hook

useShuffled

export hook useShuffled<T>(items: $ReadOnlyArray<T>, label: string): Array<T> { ... }

items, shuffled the same way on both sides of a hydration.

The shuffle is memoized over the seed, the label and the items — by the React Compiler, which is where uf's memoization comes from — so it is one shuffle rather than one per render. That matters for more than speed: a fresh draw on every render would reorder the list under the reader every time anything else on the page changed.

type

UseToggleReturn

export type UseToggleReturn = {|
  readonly on: boolean,
  readonly toggle: () => void,
  readonly set: (value: boolean) => void,
|};

A boolean and the three things a caller ever does to one.

hook

useToggle

export hook useToggle(initial: boolean = false): UseToggleReturn { ... }

A boolean with the three things a caller ever does to one.

type

UseCounterReturn

export type UseCounterReturn = {|
  readonly count: number,
  readonly increment: (by?: number) => void,
  readonly decrement: (by?: number) => void,
  readonly set: (value: number) => void,
  readonly reset: () => void,
|};

A number and the operations that suit one.

hook

useCounter

export hook useCounter(
  initial: number = 0,
  bounds?: {| readonly min?: number, readonly max?: number |},
): UseCounterReturn { ... }

A number, optionally clamped.

type

UseListReturn

export type UseListReturn<T> = {|
  readonly items: $ReadOnlyArray<T>,
  readonly set: (items: $ReadOnlyArray<T>) => void,
  readonly push: (item: T) => void,
  readonly insertAt: (index: number, item: T) => void,
  readonly replaceAt: (index: number, item: T) => void,
  readonly removeAt: (index: number) => void,
  readonly move: (from: number, to: number) => void,
  readonly clear: () => void,
|};

A list and the edits anyone makes to one.

hook

useList

export hook useList<T>(initial: $ReadOnlyArray<T> = []): UseListReturn<T> { ... }

A list, with the six edits anyone ever makes to one.

An index outside the list is not an error and not a throw: it leaves the list alone and returns the same array, so a row removed twice by a double-clicked button is removed once. @uniflowed/form's useFieldArray is the version of this for form rows, and knows about keys, errors and dirty flags; this one is for a list that is only a list.

type

UseSetReturn

export type UseSetReturn<T> = {|
  readonly items: $ReadOnlySet<T>,
  readonly has: (item: T) => boolean,
  readonly add: (item: T) => void,
  readonly remove: (item: T) => void,
  readonly toggle: (item: T) => void,
  readonly clear: () => void,
  readonly set: (items: Iterable<T>) => void,
|};

A set of members, and the questions asked of one.

hook

useSet

export hook useSet<T>(initial?: Iterable<T>): UseSetReturn<T> { ... }

A set, which is what a multi-select or a list of expanded rows actually is.

The Set is replaced rather than mutated on every change, because a Set edited in place is the same object and React would not re-render — the bug people meet the first time they put a collection in useState.

type

UseCycleReturn

export type UseCycleReturn<T> = {|
  /** The value at the current position, or `null` when the list is empty. */
  readonly value: T | null,
  readonly index: number,
  readonly next: () => void,
  readonly previous: () => void,
  readonly go: (index: number) => void,
|};

A position in a list that wraps.

hook

useCycle

export hook useCycle<T>(values: $ReadOnlyArray<T>, initialIndex: number = 0): UseCycleReturn<T> { ... }

Step through a list, wrapping at both ends.

A theme switcher, a carousel, a sort order that cycles. The counter behind this is unbounded and the position is worked out from it on each render, so values may change length between renders without the position becoming invalid — and values is deliberately not a dependency of anything, so writing the list inline in the call is free.

value is T | null rather than T because an empty list has no current value. Flow's array access would happily have said T and handed back an undefined at runtime; this package does not claim what it cannot show.

type

UseUndoableReturn

export type UseUndoableReturn<T> = {|
  readonly value: T,
  readonly set: (next: T) => void,
  readonly undo: () => void,
  readonly redo: () => void,
  readonly canUndo: boolean,
  readonly canRedo: boolean,
  /** Keep the current value, forget how it got here. */
  readonly clear: () => void,
  /** Back to the value the hook started with, history and all. */
  readonly reset: () => void,
|};

A value with the history behind and ahead of it.

hook

useUndoable

export hook useUndoable<T>(
  initial: T,
  options?: {| readonly limit?: number |},
): UseUndoableReturn<T> { ... }

A value that can be undone and redone.

One useState holding all three parts, not three: past, present and future change together, and three separate states would be three renders and a window in which they disagree.

set clears the future, which is what every editor does — typing after an undo abandons what was undone. limit bounds the past so that a long editing session does not hold every version of a large value alive; the oldest entries are dropped, and canUndo stops being true when they run out.

hook

useStorage

export hook useStorage<T>(
  key: string,
  initial: T,
  options?: {| readonly session?: boolean |},
): [T, (value: T) => void] { ... }

State kept in localStorage, or in sessionStorage.

initial is what a prerender uses and what an unset or unreadable key falls back to, so the first paint is stated rather than accidental. A value that will not parse is treated as absent rather than thrown: storage is shared with older versions of the same application, and refusing to start because of a stale key would be worse than starting fresh.

hook

useInterval

export hook useInterval(body: () => mixed, millis: number | null): void { ... }

Call body every millis, or not at all when millis is null.

Null rather than a separate enabled flag because "no interval" and "an interval of nothing" are the same thing, and one argument cannot disagree with itself.

hook

useTimeout

export hook useTimeout(body: () => mixed, millis: number | null): void { ... }

Call body once after millis, or not at all when millis is null.

hook

useDebouncedValue

export hook useDebouncedValue<T>(value: T, millis: number): T { ... }

value, but only after it has stopped changing for millis.

The classic use is a search box: the query updates on every keystroke and the request should not.

hook

useThrottledCallback

export hook useThrottledCallback<TArgs extends $ReadOnlyArray<mixed>>(
  body: (...args: TArgs) => mixed,
  millis: number,
): (...args: TArgs) => void { ... }

A callback that runs at most once per millis.

Leading edge: the first call goes through immediately and later ones inside the window are dropped, which is what a scroll or resize handler wants — the trailing-edge version would make the first paint late.

hook

useDebouncedCallback

export hook useDebouncedCallback<TArgs extends $ReadOnlyArray<mixed>>(
  body: (...args: TArgs) => mixed,
  millis: number,
): (...args: TArgs) => void { ... }

A callback that runs millis after the last time it was asked to.

Trailing edge, and it cancels itself at unmount — the version people write calls setState on a component that is gone.

hook

useAnimationFrame

export hook useAnimationFrame(
  body: (frame: {| readonly delta: number, readonly time: number |}) => mixed,
  active: boolean = true,
): void { ... }

Run body before every frame the browser paints, while active.

delta is the milliseconds since the previous frame and is zero on the first, which is what an animation integrates against: a frame that took 32ms because the tab was busy has to move twice as far as one that took 16ms, and a hand-written loop that assumes sixty a second runs at half speed on a hundred-and-twenty-hertz display.

Nothing runs before hydration: there is no frame to paint during a prerender, and the effect that would ask for one does not run there.

hook

useIdle

export hook useIdle(
  millis: number = 60_000,
  options?: {| readonly events?: $ReadOnlyArray<string> |},
): boolean { ... }

Whether the reader has stopped doing anything for millis.

false on a server and on the first client render, which is the answer that cannot be wrong: nobody is idle before the page exists, and starting at true would flash whatever the page shows an idle reader.

The listeners are passive and on the window rather than on any element, so this costs nothing on a touch screen and sees activity anywhere on the page.

hook

useNow

export hook useNow(millis: number | null = 1000, serverValue: Date | null = null): Date { ... }

The current time, re-read every millis.

The clock is read in the initial state rather than in an effect, so a client-only page has the right time on its first paint instead of a frame of something else. That read is the one impure thing in this package, and it is bounded: it happens once, the value is never re-read during a render, and a render React throws away is replaced by another whose clock is just as valid.

On a prerendered page the two renders are at two different instants, so the first one on each side has to be the *same* instant or React reports a mismatch. Under a RenderProvider that happens by itself — the anchor the server fixed travels in the markup, both sides start from it, and the real time arrives with the first effect. serverValue is the same choice made by hand, for a caller who has the instant from somewhere else and for a tree with no provider above it; it wins over the anchor when both are there, because an argument at the call site is a decision and a context is a default.

A Date rather than a Temporal.Instant, and deliberately: this value's consumers subtract it from another one to decide when to run again, which is millisecond arithmetic on a number. The Temporal-shaped reading of the same anchor is useRenderedAt in render.js, and rendering an instant is @uniflowed/web's Time.

hook

useTimeAgo

export hook useTimeAgo(
  value: Date | string | number,
  options?: {|
    readonly serverValue?: string,
    /** Override the schedule. `null` works it out once and leaves it. */
    readonly interval?: number | null,
    readonly locale?: string,
  |},
): string { ... }

"3 minutes ago", kept true while the reader looks at it.

Before hydration and on the first client render this is serverValue, defaulting to the instant's UTC ISO string — the same choice @uniflowed/web's Time makes, and for the same reason: the relative form depends on a clock and a locale that the server does not have, so rendering it on both sides would be a hydration mismatch by construction. The text is in the markup for a crawler and for a reader with no JavaScript, and becomes relative once the page is alive.

The update rate follows the distance rather than being fixed: a label from this minute is redrawn every second, one from this hour every thirty, and an older one every minute. That is why this is not "call useNow and format it" — a fixed one-second clock re-renders a week-old timestamp 604,800 times to no effect.