useLiveQuery

Call Signature#

function useLiveQuery<TContext>(queryFn): QueryResult<TContext>;

Defined in: useLiveQuery.ts:154

Subscribe a Preact component to a live query.

The hook derives the query's identity from its structured IR on each render, so values captured by the callback recompile the query when they change. A query whose IR cannot be hashed, such as one using fn.where, throws UnhashableQueryIRError unless its config supplies queryKey. While the hook is mounted, each Collection ID its queries read must keep naming one source object, or it throws SourceCollectionIdReuseError. Return undefined or null from the callback to disable the query.

Type Parameters#

TContext#

TContext extends Context

Parameters#

queryFn#

(q) => QueryBuilder<TContext>

Returns#

QueryResult<TContext>

Examples#

const { data, isLoading } = useLiveQuery((q) =>
  q
    .from({ todos: todosCollection })
    .where(({ todos }) => eq(todos.completed, false)),
)

// Disable the query until its input exists
const { data, isEnabled } = useLiveQuery((q) =>
  userId
    ? q
        .from({ todos: todosCollection })
        .where(({ todos }) => eq(todos.userId, userId))
    : undefined,
)

Call Signature#

function useLiveQuery<TContext>(queryFn): ConditionalQueryResult<TContext>;

Defined in: useLiveQuery.ts:158

Subscribe a Preact component to a live query.

The hook derives the query's identity from its structured IR on each render, so values captured by the callback recompile the query when they change. A query whose IR cannot be hashed, such as one using fn.where, throws UnhashableQueryIRError unless its config supplies queryKey. While the hook is mounted, each Collection ID its queries read must keep naming one source object, or it throws SourceCollectionIdReuseError. Return undefined or null from the callback to disable the query.

Type Parameters#

TContext#

TContext extends Context

Parameters#

queryFn#

(q) => QueryBuilder<TContext> | null | undefined

Returns#

ConditionalQueryResult<TContext>

Examples#

const { data, isLoading } = useLiveQuery((q) =>
  q
    .from({ todos: todosCollection })
    .where(({ todos }) => eq(todos.completed, false)),
)

// Disable the query until its input exists
const { data, isEnabled } = useLiveQuery((q) =>
  userId
    ? q
        .from({ todos: todosCollection })
        .where(({ todos }) => eq(todos.userId, userId))
    : undefined,
)

Call Signature#

function useLiveQuery<TContext>(queryFn): ConditionalQueryResult<TContext>;

Defined in: useLiveQuery.ts:164

Subscribe a Preact component to a live query.

The hook derives the query's identity from its structured IR on each render, so values captured by the callback recompile the query when they change. A query whose IR cannot be hashed, such as one using fn.where, throws UnhashableQueryIRError unless its config supplies queryKey. While the hook is mounted, each Collection ID its queries read must keep naming one source object, or it throws SourceCollectionIdReuseError. Return undefined or null from the callback to disable the query.

Type Parameters#

TContext#

TContext extends Context

Parameters#

queryFn#

(q) => | LiveQueryCollectionConfig<TContext, RootQueryResult<TContext>> | null | undefined

Returns#

ConditionalQueryResult<TContext>

Examples#

const { data, isLoading } = useLiveQuery((q) =>
  q
    .from({ todos: todosCollection })
    .where(({ todos }) => eq(todos.completed, false)),
)

// Disable the query until its input exists
const { data, isEnabled } = useLiveQuery((q) =>
  userId
    ? q
        .from({ todos: todosCollection })
        .where(({ todos }) => eq(todos.userId, userId))
    : undefined,
)

Call Signature#

function useLiveQuery<TResult, TKey, TUtils>(queryFn): UseConditionalLiveQueryResult<TResult, TKey, TResult[], Collection<TResult, TKey, TUtils, StandardSchemaV1<unknown, unknown>, TResult>>;

Defined in: useLiveQuery.ts:170

Subscribe a Preact component to a live query.

The hook derives the query's identity from its structured IR on each render, so values captured by the callback recompile the query when they change. A query whose IR cannot be hashed, such as one using fn.where, throws UnhashableQueryIRError unless its config supplies queryKey. While the hook is mounted, each Collection ID its queries read must keep naming one source object, or it throws SourceCollectionIdReuseError. Return undefined or null from the callback to disable the query.

Type Parameters#

TResult#

TResult extends object

TKey#

TKey extends string | number

TUtils#

TUtils extends Record<string, any>

Parameters#

queryFn#

(q) => | Collection<TResult, TKey, TUtils, StandardSchemaV1<unknown, unknown>, TResult> | null | undefined

Returns#

UseConditionalLiveQueryResult<TResult, TKey, TResult[], Collection<TResult, TKey, TUtils, StandardSchemaV1<unknown, unknown>, TResult>>

Examples#

const { data, isLoading } = useLiveQuery((q) =>
  q
    .from({ todos: todosCollection })
    .where(({ todos }) => eq(todos.completed, false)),
)

// Disable the query until its input exists
const { data, isEnabled } = useLiveQuery((q) =>
  userId
    ? q
        .from({ todos: todosCollection })
        .where(({ todos }) => eq(todos.userId, userId))
    : undefined,
)

Call Signature#

function useLiveQuery<TContext>(config): QueryResult<TContext>;

Defined in: useLiveQuery.ts:194

Subscribe to a live query described by a config object.

Type Parameters#

TContext#

TContext extends Context

Parameters#

config#

UseLiveQueryConfig<TContext>

Returns#

QueryResult<TContext>

Example#

const { data } = useLiveQuery({
  query: (q) => q.from({ todos: todosCollection }),
  gcTime: 60_000,
})

Call Signature#

function useLiveQuery<TContext>(config): ConditionalQueryResult<TContext>;

Defined in: useLiveQuery.ts:198

Subscribe a Preact component to a live query.

The hook derives the query's identity from its structured IR on each render, so values captured by the callback recompile the query when they change. A query whose IR cannot be hashed, such as one using fn.where, throws UnhashableQueryIRError unless its config supplies queryKey. While the hook is mounted, each Collection ID its queries read must keep naming one source object, or it throws SourceCollectionIdReuseError. Return undefined or null from the callback to disable the query.

Type Parameters#

TContext#

TContext extends Context

Parameters#

config#

ConditionalUseLiveQueryConfig<TContext>

Returns#

ConditionalQueryResult<TContext>

Examples#

const { data, isLoading } = useLiveQuery((q) =>
  q
    .from({ todos: todosCollection })
    .where(({ todos }) => eq(todos.completed, false)),
)

// Disable the query until its input exists
const { data, isEnabled } = useLiveQuery((q) =>
  userId
    ? q
        .from({ todos: todosCollection })
        .where(({ todos }) => eq(todos.userId, userId))
    : undefined,
)

Call Signature#

function useLiveQuery<TResult, TKey, TUtils>(liveQueryCollection): UseLiveQueryResult<TResult, TKey, TResult[], Collection<TResult, TKey, TUtils, StandardSchemaV1<unknown, unknown>, TResult>>;

Defined in: useLiveQuery.ts:212

Subscribe to an existing live-query Collection. The hook starts its sync and leaves its retention policy to the caller.

Type Parameters#

TResult#

TResult extends object

TKey#

TKey extends string | number

TUtils#

TUtils extends Record<string, any>

Parameters#

liveQueryCollection#

Collection<TResult, TKey, TUtils, StandardSchemaV1<unknown, unknown>, TResult> & NonSingleResult

Returns#

UseLiveQueryResult<TResult, TKey, TResult[], Collection<TResult, TKey, TUtils, StandardSchemaV1<unknown, unknown>, TResult>>

Example#

const activeTodos = createLiveQueryCollection((q) =>
  q.from({ todos: todosCollection }).where(({ todos }) => todos.active),
)
const { data, collection } = useLiveQuery(activeTodos)

Call Signature#

function useLiveQuery<TResult, TKey, TUtils>(liveQueryCollection): UseLiveQueryResult<TResult, TKey, TResult | undefined, Collection<TResult, TKey, TUtils, StandardSchemaV1<unknown, unknown>, TResult> & SingleResult>;

Defined in: useLiveQuery.ts:225

Subscribe a Preact component to a live query.

The hook derives the query's identity from its structured IR on each render, so values captured by the callback recompile the query when they change. A query whose IR cannot be hashed, such as one using fn.where, throws UnhashableQueryIRError unless its config supplies queryKey. While the hook is mounted, each Collection ID its queries read must keep naming one source object, or it throws SourceCollectionIdReuseError. Return undefined or null from the callback to disable the query.

Type Parameters#

TResult#

TResult extends object

TKey#

TKey extends string | number

TUtils#

TUtils extends Record<string, any>

Parameters#

liveQueryCollection#

Collection<TResult, TKey, TUtils, StandardSchemaV1<unknown, unknown>, TResult> & SingleResult

Returns#

UseLiveQueryResult<TResult, TKey, TResult | undefined, Collection<TResult, TKey, TUtils, StandardSchemaV1<unknown, unknown>, TResult> & SingleResult>

Examples#

const { data, isLoading } = useLiveQuery((q) =>
  q
    .from({ todos: todosCollection })
    .where(({ todos }) => eq(todos.completed, false)),
)

// Disable the query until its input exists
const { data, isEnabled } = useLiveQuery((q) =>
  userId
    ? q
        .from({ todos: todosCollection })
        .where(({ todos }) => eq(todos.userId, userId))
    : undefined,
)