useLiveQuery

Call Signature#

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

Defined in: useLiveQuery.ts:153

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:157

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:163

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:169

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:193

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:197

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:211

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:224

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,
)