useLiveQuery

Call Signature#

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

Defined in: useLiveQuery.ts:143

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

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: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) => | 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:159

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

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

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

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

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