web library

Jaspr hooks that integrate with browser DOM APIs.

Classes

AsyncAction<StateT, InputT>

A stable controller for user-initiated asynchronous state changes.

ClipboardController

Reads and writes plain text through the browser Clipboard API.

CounterController

Mutable integer state returned by useCounter.

ElementSize

A measured element size in the units reported for the selected observer box.

FocusController

An imperative focus handle returned by useFocus.

HistoryController

Controls and observes the browser's same-document session history.

HistoryEntry

The current browser history entry.

Hook<R>

Immutable configuration for a reusable piece of lifecycle-aware state.

HookBuilder

A hook component that delegates its build to builder.

HookComponent

A stateless Jaspr component whose build method may call hooks.

HookState<R, H extends Hook<R>>

Mutable lifecycle state associated with one Hook invocation.

IntersectionOptions

Configuration for an intersection observer.

IntersectionSnapshot

The latest intersection state for a keyed element.

ListController<T>

Mutable list state returned by useList.

MapController<K, V>

Mutable map state returned by useMap.

MutationObserverOptions

Configuration for a DOM mutation observer.

ObjectRef<T>

A mutable reference whose value survives component rebuilds.

OptimisticState<StateT, UpdateT>

A stable controller for optimistic state layered over authoritative state.

OptimisticUpdateHandle<StateT>

A handle for one pending optimistic update.

QueueController<T>

Mutable first-in, first-out state returned by useQueue.

SetController<T>

Mutable set state returned by useSet.

StableEventCallback<T, R>

A stable callable that always invokes the latest handler supplied to useEvent.

StatefulHookComponent

A stateful Jaspr component whose State.build method may call hooks.

Store<StateT, ActionT>

A mutable state store updated through actions.

ToggleController

Mutable boolean state returned by useToggle.

WebEventListenerOptions

Native DOM event-listener options.

WindowSize

The browser viewport size in CSS pixels.

WindowSizeOptions

Configuration for viewport-size updates.

Enums

ActionConcurrency

Determines how an AsyncAction handles overlapping dispatches.

ClipboardStatus

The latest clipboard operation performed by ClipboardController.

DocumentVisibility

Whether the browser document is currently visible.

MediaQueryMatch

Whether the browser currently matches a CSS media query.

PreferredColorScheme

The browser's preferred light or dark color scheme.

PreferredMotion

The browser's preferred animation and transition behavior.

ResizeObserverBox

The box measured by web.ResizeObserver.

Functions

use<R>(Hook<R> hook) → R

Registers hook in the currently building hook component and returns its value.

useAbortController([List<Object?> keys = const <Object?>[]]) → AbortController?

Creates a browser AbortController and aborts it when keys change or the hook is removed. Returns null during SSR and first hydration.

useActiveElement() → Element?

Returns the document's active element, or null during SSR and first hydration.

useAnimationFrame(AnimationFrameCallback callback, {bool enabled = true}) → void

Invokes the latest callback for every browser animation frame while enabled. No frames are scheduled during SSR.

useAsyncAction<StateT, InputT>({required StateT initialState, required AsyncActionHandler<StateT, InputT> action, ActionConcurrency concurrency = ActionConcurrency.sequential}) → AsyncAction<StateT, InputT>

Creates a stable controller for user-initiated asynchronous work.

useCallback<T extends Function>(T callback, [List<Object?> keys = const <Object>[]]) → T

Preserves callback until one of keys changes.

useClipboard() → ClipboardController

Returns a stable controller for plain-text clipboard operations.

useContext() → BuildContext

Returns the BuildContext of the currently building hook component.

useCounter([int initialValue = 0]) → CounterController

Creates stable integer state with increment, decrement, and reset operations.

useDebounced<T>(T value, Duration timeout) → T?

Returns value after it has remained unchanged for timeout.

useDisposable<T>(T create(), void dispose(T value), [List<Object?> keys = const <Object?>[]]) → T

Creates an owned resource and disposes it when keys change or its hook is removed.

useDocumentVisibility() → DocumentVisibility

Returns the document visibility state.

useEffect(Dispose? effect(), [List<Object?>? keys]) → void

Runs a synchronous browser-client side effect.

useEffectOnce(Dispose? effect()) → void

Runs effect during the hook's first browser-client build.

useElementSize(GlobalNodeKey<Element> target, {ResizeObserverBox box = ResizeObserverBox.contentBox}) → ElementSize?

Returns the latest size of target, or null before browser attachment.

useEvent<T, R>(R handler(T value)) → StableEventCallback<T, R>

Returns a stable callback that always invokes the latest handler.

useEventListener<E extends Event>(String type, void listener(E event), {WebEventTargetResolver? target, bool enabled = true, WebEventListenerOptions options = const WebEventListenerOptions()}) → void

Subscribes to a native DOM event after the first browser frame.

useExternalStore<T>(ExternalStoreSubscribe subscribe, T getSnapshot(), {T getServerSnapshot()?, ExternalStoreSnapshotEquals<T>? equals}) → T

Reads and subscribes to an external immutable snapshot.

useFocus(GlobalNodeKey<HTMLElement> target, {bool enabled = true}) → FocusController

Tracks and controls focus for target.

useFocusWithin(GlobalNodeKey<Element> target, {bool enabled = true}) → bool?

Returns whether focus is on target or one of its descendants.

useFuture<T>(Future<T>? future, {T? initialData, bool preserveState = true}) → AsyncSnapshot<T>

Subscribes to future on the browser client and returns its latest snapshot.

useHistoryState() → HistoryController?

Observes and controls same-document browser history.

useHover(GlobalNodeKey<Element> target, {bool enabled = true}) → bool?

Returns whether the pointer hovers target, or null before attachment.

useId({String prefix = 'jh'}) → String

Returns an HTML id that is stable across rebuilds, server rendering, and hydration when the component tree and hook order match.

useImperativeHandle<T extends Object>(ObjectRef<T?>? target, T createHandle(), [List<Object?>? keys]) → void

Exposes a generated handle through target until this hook is replaced or removed.

useInherited<T extends InheritedComponent>({Object? aspect}) → T?

Reads and subscribes to the nearest Jaspr inherited component of type T.

useIntersection(GlobalNodeKey<Element> target, [IntersectionOptions options = const IntersectionOptions()]) → IntersectionSnapshot?

Returns the latest intersection state for target.

useInterval(VoidCallback callback, Duration? interval, {bool immediate = false}) → void

Repeatedly invokes the latest callback every interval on the browser client.

useIsMounted() → IsMounted

Returns a stable callback that becomes false after hook disposal.

useLatest<T>(T value) → ObjectRef<T>

Keeps the latest value in a stable reference without requesting rebuilds.

useList<T>([Iterable<T> initialValue = const <Never>[]]) → ListController<T>

Creates stable list state initialized with a snapshot of initialValue.

useListenable<T extends Listenable?>(T listenable) → T

Returns listenable and rebuilds when it notifies on the browser client.

useListenableSelector<R>(Listenable? listenable, R selector()) → R

Rebuilds only when the result of selector changes.

useMap<K, V>([Map<K, V> initialValue = const <Never, Never>{}]) → MapController<K, V>

Creates stable map state initialized with a snapshot of initialValue.

useMediaQuery(String query) → MediaQueryMatch

Returns whether the document matches query.

useMemoized<T>(T valueBuilder(), [List<Object?> keys = const <Object>[]]) → T

Evaluates valueBuilder once and caches its value until keys change.

useMount(VoidCallback effect) → void

Runs effect during the hook's first browser-client build.

useMutationObserver(GlobalNodeKey<Node> target, WebMutationCallback callback, {MutationObserverOptions options = const MutationObserverOptions()}) → void

Observes DOM mutations beneath target.

useNodeKey<T extends Node>({String? debugLabel}) → GlobalNodeKey<T>

Creates a stable Jaspr key that exposes its rendered browser node.

useOnClickOutside(GlobalNodeKey<Element> target, void listener(PointerEvent event), {List<GlobalNodeKey<Element>> additionalTargets = const <GlobalNodeKey<web.Element>>[], bool enabled = true}) → void

Calls listener for pointer presses outside target and related elements.

useOnDocumentVisibilityChange(DocumentVisibilityCallback callback) → void

Calls callback when document visibility changes after initial browser synchronization.

useOnListenableChange(Listenable? listenable, VoidCallback listener) → void

Invokes listener when listenable notifies on the browser client.

useOnMediaQueryChange(String query, MediaQueryCallback callback) → void

Calls callback when query changes after initial browser synchronization.

useOnPreferredColorSchemeChange(PreferredColorSchemeCallback callback) → void

Calls callback when the preferred scheme changes after initial browser synchronization.

useOnPreferredMotionChange(PreferredMotionCallback callback) → void

Calls callback when the browser's preferred motion behavior changes.

useOnStreamChange<T>(Stream<T>? stream, {void onData(T event)?, void onError(Object error, StackTrace stackTrace)?, void onDone()?, bool? cancelOnError}) → StreamSubscription<T>?

Listens to stream on the browser client and invokes the latest callbacks.

useOptimistic<StateT, UpdateT>(StateT authoritativeState, StateT reducer(StateT current, UpdateT update)) → OptimisticState<StateT, UpdateT>

Layers optimistic updates over authoritativeState.

usePostFrameEffect(Dispose? effect(), [List<Object?>? keys]) → void

Runs effect after the next completed browser-client frame.

usePreferredColorScheme() → PreferredColorScheme

Returns the browser's preferred color scheme.

usePreferredMotion() → PreferredMotion

Returns the browser's preferred animation and transition behavior.

usePrevious<T>(T value) → T?

Returns the value supplied during the preceding build, or null initially.

useQueue<T>([Iterable<T> initialValue = const <Never>[]]) → QueueController<T>

Creates stable queue state initialized with a snapshot of initialValue.

useReducer<StateT, ActionT>(Reducer<StateT, ActionT> reducer, {required StateT initialState, required ActionT initialAction}) → Store<StateT, ActionT>

Creates a reducer-backed Store.

useRef<T>(T initialValue) → ObjectRef<T>

Preserves a mutable ObjectRef across builds.

useSet<T>([Iterable<T> initialValue = const <Never>[]]) → SetController<T>

Creates stable set state initialized with a snapshot of initialValue.

useState<T>(T initialData) → ValueNotifier<T>

Creates a ValueNotifier that rebuilds its owning component when changed.

useStream<T>(Stream<T>? stream, {T? initialData, bool preserveState = true}) → AsyncSnapshot<T>

Subscribes to stream on the browser client and returns its latest snapshot.

useStreamController<T>({bool sync = false, VoidCallback? onListen, VoidCallback? onCancel, List<Object?>? keys}) → StreamController<T>

Creates a broadcast StreamController and closes it on hook disposal.

useTimeout(VoidCallback callback, Duration? delay) → void

Invokes the latest callback once after delay on the browser client.

useToggle([bool initialValue = false]) → ToggleController

Creates stable boolean state with toggle and reset operations.

useUnmount(VoidCallback effect) → void

Runs effect when the hook is removed from a browser-client component.

useUpdateEffect(Dispose? effect(), [List<Object?>? keys]) → void

Runs effect during updates while skipping the initial client build.

useValueChanged<T, R>(T value, R? valueChange(T oldValue, R? oldResult)) → R?

Calls valueChange when value changes and returns its latest result.

useValueListenable<T>(ValueListenable<T> valueListenable) → T

Subscribes to valueListenable and returns its current value.

useValueNotifier<T>(T initialData, [List<Object?>? keys]) → ValueNotifier<T>

Creates a ValueNotifier and disposes it when its hook is removed.

useWindowSize([WindowSizeOptions options = const WindowSizeOptions()]) → WindowSize?

Returns the browser viewport size, or null during SSR and first hydration.

Typedefs

AnimationFrameCallback = void Function(Duration timestamp)

Receives the high-resolution timestamp for a browser animation frame.

AsyncActionHandler<StateT, InputT> = FutureOr<StateT> Function(StateT previousState, InputT input)

Computes the next state for an asynchronous action.

Dispose = void Function()

A cleanup function returned by an effect.

DocumentVisibilityCallback = void Function(DocumentVisibility previous, DocumentVisibility current)

Callback invoked after an established document visibility value changes.

ExternalStoreSnapshotEquals<T> = bool Function(T previous, T current)

Decides whether two external-store snapshots represent the same value.

ExternalStoreSubscribe = Dispose Function(VoidCallback notify)

Subscribes notify to an external store and returns its unsubscribe callback.

IsMounted = bool Function()

Function that reports whether its hook remains mounted.

MediaQueryCallback = void Function(MediaQueryMatch previous, MediaQueryMatch current)

Callback invoked after an established media-query result changes.

PreferredColorSchemeCallback = void Function(PreferredColorScheme previous, PreferredColorScheme current)

Callback invoked after an established preferred color scheme changes.

PreferredMotionCallback = void Function(PreferredMotion previous, PreferredMotion current)

Callback invoked after an established preferred-motion value changes.

Reducer<StateT, ActionT> = StateT Function(StateT state, ActionT action)

Combines a state and action into the next state.

WebEventTargetResolver = EventTarget? Function()

Resolves an event target after the browser has rendered the current frame.

WebMutationCallback = void Function(List<MutationRecord> records)

Receives DOM mutations observed for a keyed node.

Exceptions / Errors

ActionCancelledException

Thrown when a queued action is invalidated before it starts.

ActionDroppedException

Thrown when ActionConcurrency.drop rejects an overlapping dispatch.