composables library

Lark Composables — Reusable reactive utilities.

Import separately to enable tree-shaking when not using composables.

Classes

CookieOptions

Cookie options.

CookieStorage

Cookie storage abstraction.

Debounced<T>

Result type for useDebounce.

HttpResponse

Simple HTTP response wrapper.

MemoryStorage

In-memory storage fallback (for SSR or testing).

MutationOptions<TData, TVariables, TContext>

Configuration options for a mutation.

PageResult<T>

Page result from fetcher.

Previous<T>

Result type for usePrevious.

QueryClient

Central manager for query caching and invalidation.

QueryOptions<T>

Configuration options for a query.

Storage

Abstract storage interface (implemented differently for web/server).

Toggle

Result type for useToggle.

Enums

ColorScheme

Dark mode preference.

FetchStatus

Detailed fetch status for distinguishing types of loading.

QueryStatus

The current status of a query.

Properties

localStorage → Storage

Get localStorage (falls back to memory storage).

no setter

queryClient → QueryClient

Global query client instance.

final

sessionStorage → Storage

Get sessionStorage (falls back to memory storage).

no setter

Functions

configureCookies(CookieStorage storage) → void

Configure cookie storage.

configureDarkModeAutoApply(void apply(bool isDark)) → void

Configure auto-application of dark mode class.

configureDarkModeDefaultPreference(ColorScheme preference) → void

Configure the default preference used when nothing is stored yet.

configureDarkModeDetection(bool detector()) → void

Configure system preference detection.

configureDarkModeDomSync({required bool enabled}) → void

Enable/disable applying dark class updates to the DOM.

configureDarkModeSystemObserver(void Function()? observer(void onChange(bool isDark))) → void

Configure system preference observation for live updates.

configureFetch({required HttpGet get, required HttpPost post}) → void

Configure the HTTP client for fetch operations.

configureStorage({Storage? local, Storage? session}) → void

Configure storage for the platform.

resetDarkModeSystemTrackingForTesting() → void

Test helper to reset cached system dark mode tracking state.

useAsync<T>(Future<T> fn(), {bool immediate = false}) → AsyncResult<T>

Manage async operation state.

useCookie(String name, {CookieOptions options = const CookieOptions()}) → CookieResult

Create a reactive ref backed by a cookie.

useDarkMode({String storageKey = _darkModeStorageKey}) → DarkModeResult

Create a reactive dark mode controller with persistence.

useDebounce<T>(Ref<T> source, Duration delay) → Debounced<T>

Creates a debounced version of source.

useDom() → DomResult

Creates browser-safe DOM helpers.

useFetch<T>(String url, {T transform(dynamic json)?, Map<String, String>? headers, bool immediate = true, bool server = true, bool client = true, String? key}) → FetchResult<T>

Fetch data from a URL with reactive state tracking.

useInfiniteScroll<T>({required Future<PageResult<T>> fetcher(int page), bool immediate = true}) → InfiniteScrollResult<T>

Create an infinite scroll data source.

useLazyFetch<T>(String url, {T transform(dynamic json)?, Map<String, String>? headers}) → FetchResult<T>

Lazy fetch - only fetches when execute() is called.

useLazyQuery<T>({required QueryKey key, required Future<T> queryFn(), required Ref<bool> enabled, QueryOptions<T>? options}) → QueryResult<T>

Create a disabled query that only fetches when enabled.

useLocalStorage(String key, {String? defaultValue}) → StorageResult<String?>

Create a reactive ref backed by localStorage.

useLocalStorageJson<T>({required String key, required T defaultValue, required T fromJson(Map<String, dynamic>), required Map<String, dynamic> toJson(T)}) → StorageResult<T>

Typed localStorage helper with JSON serialization.

useMutation<TData, TVariables, TContext>({required Future<TData> mutationFn(TVariables variables), MutationOptions<TData, TVariables, TContext>? options}) → MutationResult<TData, TVariables>

Perform data modifications with optimistic updates and cache invalidation.

usePagination<T>({required Future<PageResult<T>> fetcher(int page), int initialPage = 1, bool immediate = true}) → PaginationResult<T>

Create a paginated data source.

usePolling<T>({required Future<T> fetcher(), required Duration interval, bool immediate = true}) → PollingResult<T>

Poll data at regular intervals.

usePost<T>(String url, {T transform(dynamic json)?, Map<String, String>? headers}) → HttpMutationResult<T>

Perform a POST request.

usePrevious<T>(Ref<T> source) → Previous<T>

Creates a ref that tracks the previous value of source.

useQuery<T>({required QueryKey key, required Future<T> queryFn(), QueryOptions<T>? options}) → QueryResult<T>

Fetch and cache server data with automatic state management.

useSessionStorage(String key, {String? defaultValue}) → StorageResult<String?>

Create a reactive ref backed by sessionStorage.

useThrottle<T>(Ref<T> source, Duration interval) → Debounced<T>

Creates a throttled version of source.

useToggle([bool initial = false]) → Toggle

Creates a reactive boolean toggle.

Typedefs

AsyncResult<T> = ({Ref<T?> data, Ref<String?> error, Future<void> Function() execute, Ref<bool> loading, void Function() reset})

Result type for useAsync.

CookieResult = ({void Function() remove, void Function(String value) set, Ref<String?> value})

Result type for useCookie.

DarkModeResult = ({ReadonlyRef<bool> isDark, ReadonlyRef<String> mode, Ref<ColorScheme> preference, void Function() setDark, void Function() setLight, void Function() setSystem, void Function() toggle})

Result type for useDarkMode.

DomPoint = ({double x, double y})

DomResult = ({bool available, bool Function(String id, {bool preventScroll}) focusById, void Function() lockBodyScroll, bool Function(String selector, {String block, String inline, bool smooth}) scrollIntoView, DomPoint Function() scrollPosition, bool Function(String id, {double offset, bool smooth}) scrollToId, bool Function({double? left, bool smooth, double? top}) scrollToPosition, bool Function({bool smooth}) scrollToTop, void Function() unlockBodyScroll, DomViewport Function() viewport})

Result record for useDom.

DomViewport = ({double height, double width})

FetchResult<T> = ({Ref<T?> data, Ref<String?> error, Future<void> Function() execute, Ref<bool> loading, Future<void> Function() refresh})

Result type for useFetch.

HttpGet = Future<HttpResponse> Function(String url, {Map<String, String>? headers})

HttpMutationResult<T> = ({Ref<T?> data, Ref<String?> error, Future<void> Function(Object? body) execute, Ref<bool> loading})

Result type for mutations (POST, PUT, DELETE).

HttpPost = Future<HttpResponse> Function(String url, {Object? body, Map<String, String>? headers})

InfiniteScrollResult<T> = ({Ref<String?> error, Ref<bool> hasMore, Ref<bool> initialLoading, Ref<List<T>> items, Future<void> Function() loadMore, Ref<bool> loading, Future<void> Function() refresh})

Result type for useInfiniteScroll.

MutationResult<TData, TVariables> = ({Ref<TData?> data, Ref<String?> error, ReadonlyRef<bool> isError, ReadonlyRef<bool> isIdle, ReadonlyRef<bool> isPending, ReadonlyRef<bool> isSuccess, void Function(TVariables variables) mutate, Future<TData> Function(TVariables variables) mutateAsync, void Function() reset, Ref<QueryStatus> status, Ref<TVariables?> variables})

Result type for useMutation.

PaginationResult<T> = ({Ref<String?> error, Future<void> Function(int page) goToPage, Ref<bool> hasMore, Ref<List<T>> items, Future<void> Function() loadMore, Future<void> Function() loadPrevious, Ref<bool> loading, Ref<int> page, Future<void> Function() refresh, Future<void> Function() reset, Ref<int?> total})

Result type for usePagination.

PollingResult<T> = ({Ref<bool> active, Ref<T?> data, Ref<String?> error, Future<void> Function() fetchNow, void Function() start, void Function() stop})

Result type for usePolling.

QueryKey = List<Object?>

A query key uniquely identifies cached data.

QueryResult<T> = ({Ref<T?> data, Ref<DateTime?> dataUpdatedAt, void Function() dispose, Ref<String?> error, Ref<FetchStatus> fetchStatus, ReadonlyRef<bool> isError, ReadonlyRef<bool> isFetching, ReadonlyRef<bool> isLoading, ReadonlyRef<bool> isPending, ReadonlyRef<bool> isStale, ReadonlyRef<bool> isSuccess, Future<void> Function() refetch, Ref<QueryStatus> status})

Result type for useQuery.

StorageResult<T> = ({void Function() remove, void Function(T value) set, Ref<T> value})

Result type for useLocalStorage.