📄 tanstack/db/latest/docs/framework/react/reference/functions/useLiveQuery

File: useLiveQuery.md | Updated: 11/15/2025

Source: https://tanstack.com/db/latest/docs/framework/react/reference/functions/useLiveQuery



TanStack

DB v0v0

Search...

+ K

Auto

Log In

TanStack StartRC

Docs Examples GitHub Contributors

TanStack Router

Docs Examples GitHub Contributors

TanStack Query

Docs Examples GitHub Contributors

TanStack Table

Docs Examples Github Contributors

TanStack Formnew

Docs Examples Github Contributors

TanStack DBbeta

Docs Github Contributors

TanStack Virtual

Docs Examples Github Contributors

TanStack Paceralpha

Docs Examples Github Contributors

TanStack Storealpha

Docs Examples Github Contributors

TanStack Devtoolsalpha

Docs Github Contributors

More Libraries

Maintainers Partners Support Learn StatsBETA Discord Merch Blog GitHub Ethos Brand Guide

Documentation

Framework

React logo

React

Version

Latest

Search...

+ K

Menu

Getting Started

Guides

Collections

Frameworks

Community

API Reference

Framework

React logo

React

Version

Latest

Menu

Getting Started

Guides

Collections

Frameworks

Community

API Reference

On this page

useLiveQuery

Copy Markdown

Function: useLiveQuery()
======================== Call Signature
--------------

ts

function useLiveQuery<TContext>(queryFn, deps?): object;


function useLiveQuery<TContext>(queryFn, deps?): object;

Defined in: useLiveQuery.ts:84

Create a live query using a query function

### Type Parameters #### TContext

TContext extends Context

### Parameters #### queryFn

(q) => QueryBuilder<TContext>

Query function that defines what data to fetch

#### deps?

unknown[]

Array of dependencies that trigger query re-execution when changed

### Returns

object

Object with reactive data, state, and status information

#### collection

ts

collection: Collection<{ [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] }, string | number, {
}>;


collection: Collection<{ [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] }, string | number, {
}>;

#### data

ts

data: InferResultType<TContext>;


data: InferResultType<TContext>;

#### isCleanedUp

ts

isCleanedUp: boolean;


isCleanedUp: boolean;

#### isEnabled

ts

isEnabled: true;


isEnabled: true;

#### isError

ts

isError: boolean;


isError: boolean;

#### isIdle

ts

isIdle: boolean;


isIdle: boolean;

#### isLoading

ts

isLoading: boolean;


isLoading: boolean;

#### isReady

ts

isReady: boolean;


isReady: boolean;

#### state

ts

state: Map<string | number, { [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] }>;


state: Map<string | number, { [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] }>;

#### status

ts

status: CollectionStatus;


status: CollectionStatus;

### Examples

ts

// Basic query with object syntax
const { data, isLoading } = useLiveQuery((q) =>
  q.from({ todos: todosCollection })
   .where(({ todos }) => eq(todos.completed, false))
   .select(({ todos }) => ({ id: todos.id, text: todos.text }))
)


// Basic query with object syntax
const { data, isLoading } = useLiveQuery((q) =>
  q.from({ todos: todosCollection })
   .where(({ todos }) => eq(todos.completed, false))
   .select(({ todos }) => ({ id: todos.id, text: todos.text }))
)

ts

// Single result query
const { data } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)


// Single result query
const { data } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)

ts

// With dependencies that trigger re-execution
const { data, state } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [minPriority] // Re-run when minPriority changes
)


// With dependencies that trigger re-execution
const { data, state } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [minPriority] // Re-run when minPriority changes
)

ts

// Join pattern
const { data } = useLiveQuery((q) =>
  q.from({ issues: issueCollection })
   .join({ persons: personCollection }, ({ issues, persons }) =>
     eq(issues.userId, persons.id)
   )
   .select(({ issues, persons }) => ({
     id: issues.id,
     title: issues.title,
     userName: persons.name
   }))
)


// Join pattern
const { data } = useLiveQuery((q) =>
  q.from({ issues: issueCollection })
   .join({ persons: personCollection }, ({ issues, persons }) =>
     eq(issues.userId, persons.id)
   )
   .select(({ issues, persons }) => ({
     id: issues.id,
     title: issues.title,
     userName: persons.name
   }))
)

ts

// Handle loading and error states
const { data, isLoading, isError, status } = useLiveQuery((q) =>
  q.from({ todos: todoCollection })
)

if (isLoading) return <div>Loading...</div>
if (isError) return <div>Error: {status}</div>

return (
  <ul>
    {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
  </ul>
)


// Handle loading and error states
const { data, isLoading, isError, status } = useLiveQuery((q) =>
  q.from({ todos: todoCollection })
)

if (isLoading) return <div>Loading...</div>
if (isError) return <div>Error: {status}</div>

return (
  <ul>
    {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
  </ul>
)

Call Signature
--------------

ts

function useLiveQuery<TContext>(queryFn, deps?): object;


function useLiveQuery<TContext>(queryFn, deps?): object;

Defined in: useLiveQuery.ts:101

Create a live query using a query function

### Type Parameters #### TContext

TContext extends Context

### Parameters #### queryFn

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

Query function that defines what data to fetch

#### deps?

unknown[]

Array of dependencies that trigger query re-execution when changed

### Returns

object

Object with reactive data, state, and status information

#### collection

ts

collection: 
  | Collection<{ [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] }, string | number, {
}, StandardSchemaV1<unknown, unknown>, { [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] }>
  | undefined;


collection: 
  | Collection<{ [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] }, string | number, {
}, StandardSchemaV1<unknown, unknown>, { [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] }>
  | undefined;

#### data

ts

data: InferResultType<TContext> | undefined;


data: InferResultType<TContext> | undefined;

#### isCleanedUp

ts

isCleanedUp: boolean;


isCleanedUp: boolean;

#### isEnabled

ts

isEnabled: boolean;


isEnabled: boolean;

#### isError

ts

isError: boolean;


isError: boolean;

#### isIdle

ts

isIdle: boolean;


isIdle: boolean;

#### isLoading

ts

isLoading: boolean;


isLoading: boolean;

#### isReady

ts

isReady: boolean;


isReady: boolean;

#### state

ts

state: 
  | Map<string | number, { [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] }>
  | undefined;


state: 
  | Map<string | number, { [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] }>
  | undefined;

#### status

ts

status: UseLiveQueryStatus;


status: UseLiveQueryStatus;

### Examples

ts

// Basic query with object syntax
const { data, isLoading } = useLiveQuery((q) =>
  q.from({ todos: todosCollection })
   .where(({ todos }) => eq(todos.completed, false))
   .select(({ todos }) => ({ id: todos.id, text: todos.text }))
)


// Basic query with object syntax
const { data, isLoading } = useLiveQuery((q) =>
  q.from({ todos: todosCollection })
   .where(({ todos }) => eq(todos.completed, false))
   .select(({ todos }) => ({ id: todos.id, text: todos.text }))
)

ts

// Single result query
const { data } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)


// Single result query
const { data } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)

ts

// With dependencies that trigger re-execution
const { data, state } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [minPriority] // Re-run when minPriority changes
)


// With dependencies that trigger re-execution
const { data, state } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [minPriority] // Re-run when minPriority changes
)

ts

// Join pattern
const { data } = useLiveQuery((q) =>
  q.from({ issues: issueCollection })
   .join({ persons: personCollection }, ({ issues, persons }) =>
     eq(issues.userId, persons.id)
   )
   .select(({ issues, persons }) => ({
     id: issues.id,
     title: issues.title,
     userName: persons.name
   }))
)


// Join pattern
const { data } = useLiveQuery((q) =>
  q.from({ issues: issueCollection })
   .join({ persons: personCollection }, ({ issues, persons }) =>
     eq(issues.userId, persons.id)
   )
   .select(({ issues, persons }) => ({
     id: issues.id,
     title: issues.title,
     userName: persons.name
   }))
)

ts

// Handle loading and error states
const { data, isLoading, isError, status } = useLiveQuery((q) =>
  q.from({ todos: todoCollection })
)

if (isLoading) return <div>Loading...</div>
if (isError) return <div>Error: {status}</div>

return (
  <ul>
    {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
  </ul>
)


// Handle loading and error states
const { data, isLoading, isError, status } = useLiveQuery((q) =>
  q.from({ todos: todoCollection })
)

if (isLoading) return <div>Loading...</div>
if (isError) return <div>Error: {status}</div>

return (
  <ul>
    {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
  </ul>
)

Call Signature
--------------

ts

function useLiveQuery<TContext>(queryFn, deps?): object;


function useLiveQuery<TContext>(queryFn, deps?): object;

Defined in: useLiveQuery.ts:120

Create a live query using a query function

### Type Parameters #### TContext

TContext extends Context

### Parameters #### queryFn

(q) => | LiveQueryCollectionConfig<TContext, { [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] } & object> | null | undefined

Query function that defines what data to fetch

#### deps?

unknown[]

Array of dependencies that trigger query re-execution when changed

### Returns

object

Object with reactive data, state, and status information

#### collection

ts

collection: 
  | Collection<{ [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] }, string | number, {
}, StandardSchemaV1<unknown, unknown>, { [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] }>
  | undefined;


collection: 
  | Collection<{ [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] }, string | number, {
}, StandardSchemaV1<unknown, unknown>, { [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] }>
  | undefined;

#### data

ts

data: InferResultType<TContext> | undefined;


data: InferResultType<TContext> | undefined;

#### isCleanedUp

ts

isCleanedUp: boolean;


isCleanedUp: boolean;

#### isEnabled

ts

isEnabled: boolean;


isEnabled: boolean;

#### isError

ts

isError: boolean;


isError: boolean;

#### isIdle

ts

isIdle: boolean;


isIdle: boolean;

#### isLoading

ts

isLoading: boolean;


isLoading: boolean;

#### isReady

ts

isReady: boolean;


isReady: boolean;

#### state

ts

state: 
  | Map<string | number, { [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] }>
  | undefined;


state: 
  | Map<string | number, { [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] }>
  | undefined;

#### status

ts

status: UseLiveQueryStatus;


status: UseLiveQueryStatus;

### Examples

ts

// Basic query with object syntax
const { data, isLoading } = useLiveQuery((q) =>
  q.from({ todos: todosCollection })
   .where(({ todos }) => eq(todos.completed, false))
   .select(({ todos }) => ({ id: todos.id, text: todos.text }))
)


// Basic query with object syntax
const { data, isLoading } = useLiveQuery((q) =>
  q.from({ todos: todosCollection })
   .where(({ todos }) => eq(todos.completed, false))
   .select(({ todos }) => ({ id: todos.id, text: todos.text }))
)

ts

// Single result query
const { data } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)


// Single result query
const { data } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)

ts

// With dependencies that trigger re-execution
const { data, state } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [minPriority] // Re-run when minPriority changes
)


// With dependencies that trigger re-execution
const { data, state } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [minPriority] // Re-run when minPriority changes
)

ts

// Join pattern
const { data } = useLiveQuery((q) =>
  q.from({ issues: issueCollection })
   .join({ persons: personCollection }, ({ issues, persons }) =>
     eq(issues.userId, persons.id)
   )
   .select(({ issues, persons }) => ({
     id: issues.id,
     title: issues.title,
     userName: persons.name
   }))
)


// Join pattern
const { data } = useLiveQuery((q) =>
  q.from({ issues: issueCollection })
   .join({ persons: personCollection }, ({ issues, persons }) =>
     eq(issues.userId, persons.id)
   )
   .select(({ issues, persons }) => ({
     id: issues.id,
     title: issues.title,
     userName: persons.name
   }))
)

ts

// Handle loading and error states
const { data, isLoading, isError, status } = useLiveQuery((q) =>
  q.from({ todos: todoCollection })
)

if (isLoading) return <div>Loading...</div>
if (isError) return <div>Error: {status}</div>

return (
  <ul>
    {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
  </ul>
)


// Handle loading and error states
const { data, isLoading, isError, status } = useLiveQuery((q) =>
  q.from({ todos: todoCollection })
)

if (isLoading) return <div>Loading...</div>
if (isError) return <div>Error: {status}</div>

return (
  <ul>
    {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
  </ul>
)

Call Signature
--------------

ts

function useLiveQuery<TResult, TKey, TUtils>(queryFn, deps?): object;


function useLiveQuery<TResult, TKey, TUtils>(queryFn, deps?): object;

Defined in: useLiveQuery.ts:139

Create a live query using a query function

### 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

Query function that defines what data to fetch

#### deps?

unknown[]

Array of dependencies that trigger query re-execution when changed

### Returns

object

Object with reactive data, state, and status information

#### collection

ts

collection: 
  | Collection<TResult, TKey, TUtils, StandardSchemaV1<unknown, unknown>, TResult>
  | undefined;


collection: 
  | Collection<TResult, TKey, TUtils, StandardSchemaV1<unknown, unknown>, TResult>
  | undefined;

#### data

ts

data: TResult[] | undefined;


data: TResult[] | undefined;

#### isCleanedUp

ts

isCleanedUp: boolean;


isCleanedUp: boolean;

#### isEnabled

ts

isEnabled: boolean;


isEnabled: boolean;

#### isError

ts

isError: boolean;


isError: boolean;

#### isIdle

ts

isIdle: boolean;


isIdle: boolean;

#### isLoading

ts

isLoading: boolean;


isLoading: boolean;

#### isReady

ts

isReady: boolean;


isReady: boolean;

#### state

ts

state: Map<TKey, TResult> | undefined;


state: Map<TKey, TResult> | undefined;

#### status

ts

status: UseLiveQueryStatus;


status: UseLiveQueryStatus;

### Examples

ts

// Basic query with object syntax
const { data, isLoading } = useLiveQuery((q) =>
  q.from({ todos: todosCollection })
   .where(({ todos }) => eq(todos.completed, false))
   .select(({ todos }) => ({ id: todos.id, text: todos.text }))
)


// Basic query with object syntax
const { data, isLoading } = useLiveQuery((q) =>
  q.from({ todos: todosCollection })
   .where(({ todos }) => eq(todos.completed, false))
   .select(({ todos }) => ({ id: todos.id, text: todos.text }))
)

ts

// Single result query
const { data } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)


// Single result query
const { data } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)

ts

// With dependencies that trigger re-execution
const { data, state } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [minPriority] // Re-run when minPriority changes
)


// With dependencies that trigger re-execution
const { data, state } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [minPriority] // Re-run when minPriority changes
)

ts

// Join pattern
const { data } = useLiveQuery((q) =>
  q.from({ issues: issueCollection })
   .join({ persons: personCollection }, ({ issues, persons }) =>
     eq(issues.userId, persons.id)
   )
   .select(({ issues, persons }) => ({
     id: issues.id,
     title: issues.title,
     userName: persons.name
   }))
)


// Join pattern
const { data } = useLiveQuery((q) =>
  q.from({ issues: issueCollection })
   .join({ persons: personCollection }, ({ issues, persons }) =>
     eq(issues.userId, persons.id)
   )
   .select(({ issues, persons }) => ({
     id: issues.id,
     title: issues.title,
     userName: persons.name
   }))
)

ts

// Handle loading and error states
const { data, isLoading, isError, status } = useLiveQuery((q) =>
  q.from({ todos: todoCollection })
)

if (isLoading) return <div>Loading...</div>
if (isError) return <div>Error: {status}</div>

return (
  <ul>
    {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
  </ul>
)


// Handle loading and error states
const { data, isLoading, isError, status } = useLiveQuery((q) =>
  q.from({ todos: todoCollection })
)

if (isLoading) return <div>Loading...</div>
if (isError) return <div>Error: {status}</div>

return (
  <ul>
    {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
  </ul>
)

Call Signature
--------------

ts

function useLiveQuery<TContext, TResult, TKey, TUtils>(queryFn, deps?): object;


function useLiveQuery<TContext, TResult, TKey, TUtils>(queryFn, deps?): object;

Defined in: useLiveQuery.ts:162

Create a live query using a query function

### Type Parameters #### TContext

TContext extends Context

#### TResult

TResult extends object

#### TKey

TKey extends string | number

#### TUtils

TUtils extends Record<string, any>

### Parameters #### queryFn

(q) => | QueryBuilder<TContext> | LiveQueryCollectionConfig<TContext, { [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] } & object> | Collection<TResult, TKey, TUtils, StandardSchemaV1<unknown, unknown>, TResult> | null | undefined

Query function that defines what data to fetch

#### deps?

unknown[]

Array of dependencies that trigger query re-execution when changed

### Returns

object

Object with reactive data, state, and status information

#### collection

ts

collection: 
  | Collection<TResult, TKey, TUtils, StandardSchemaV1<unknown, unknown>, TResult>
  | Collection<{ [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] }, string | number, {
}, StandardSchemaV1<unknown, unknown>, { [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] }>
  | undefined;


collection: 
  | Collection<TResult, TKey, TUtils, StandardSchemaV1<unknown, unknown>, TResult>
  | Collection<{ [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] }, string | number, {
}, StandardSchemaV1<unknown, unknown>, { [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] }>
  | undefined;

#### data

ts

data: InferResultType<TContext> | TResult[] | undefined;


data: InferResultType<TContext> | TResult[] | undefined;

#### isCleanedUp

ts

isCleanedUp: boolean;


isCleanedUp: boolean;

#### isEnabled

ts

isEnabled: boolean;


isEnabled: boolean;

#### isError

ts

isError: boolean;


isError: boolean;

#### isIdle

ts

isIdle: boolean;


isIdle: boolean;

#### isLoading

ts

isLoading: boolean;


isLoading: boolean;

#### isReady

ts

isReady: boolean;


isReady: boolean;

#### state

ts

state: 
  | Map<string | number, { [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] }>
  | Map<TKey, TResult>
  | undefined;


state: 
  | Map<string | number, { [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] }>
  | Map<TKey, TResult>
  | undefined;

#### status

ts

status: UseLiveQueryStatus;


status: UseLiveQueryStatus;

### Examples

ts

// Basic query with object syntax
const { data, isLoading } = useLiveQuery((q) =>
  q.from({ todos: todosCollection })
   .where(({ todos }) => eq(todos.completed, false))
   .select(({ todos }) => ({ id: todos.id, text: todos.text }))
)


// Basic query with object syntax
const { data, isLoading } = useLiveQuery((q) =>
  q.from({ todos: todosCollection })
   .where(({ todos }) => eq(todos.completed, false))
   .select(({ todos }) => ({ id: todos.id, text: todos.text }))
)

ts

// Single result query
const { data } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)


// Single result query
const { data } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)

ts

// With dependencies that trigger re-execution
const { data, state } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [minPriority] // Re-run when minPriority changes
)


// With dependencies that trigger re-execution
const { data, state } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [minPriority] // Re-run when minPriority changes
)

ts

// Join pattern
const { data } = useLiveQuery((q) =>
  q.from({ issues: issueCollection })
   .join({ persons: personCollection }, ({ issues, persons }) =>
     eq(issues.userId, persons.id)
   )
   .select(({ issues, persons }) => ({
     id: issues.id,
     title: issues.title,
     userName: persons.name
   }))
)


// Join pattern
const { data } = useLiveQuery((q) =>
  q.from({ issues: issueCollection })
   .join({ persons: personCollection }, ({ issues, persons }) =>
     eq(issues.userId, persons.id)
   )
   .select(({ issues, persons }) => ({
     id: issues.id,
     title: issues.title,
     userName: persons.name
   }))
)

ts

// Handle loading and error states
const { data, isLoading, isError, status } = useLiveQuery((q) =>
  q.from({ todos: todoCollection })
)

if (isLoading) return <div>Loading...</div>
if (isError) return <div>Error: {status}</div>

return (
  <ul>
    {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
  </ul>
)


// Handle loading and error states
const { data, isLoading, isError, status } = useLiveQuery((q) =>
  q.from({ todos: todoCollection })
)

if (isLoading) return <div>Loading...</div>
if (isError) return <div>Error: {status}</div>

return (
  <ul>
    {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
  </ul>
)

Call Signature
--------------

ts

function useLiveQuery<TContext>(config, deps?): object;


function useLiveQuery<TContext>(config, deps?): object;

Defined in: useLiveQuery.ts:230

Create a live query using configuration object

### Type Parameters #### TContext

TContext extends Context

### Parameters #### config

LiveQueryCollectionConfig<TContext>

Configuration object with query and options

#### deps?

unknown[]

Array of dependencies that trigger query re-execution when changed

### Returns

object

Object with reactive data, state, and status information

#### collection

ts

collection: Collection<{ [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] }, string | number, {
}>;


collection: Collection<{ [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] }, string | number, {
}>;

#### data

ts

data: InferResultType<TContext>;


data: InferResultType<TContext>;

#### isCleanedUp

ts

isCleanedUp: boolean;


isCleanedUp: boolean;

#### isEnabled

ts

isEnabled: true;


isEnabled: true;

#### isError

ts

isError: boolean;


isError: boolean;

#### isIdle

ts

isIdle: boolean;


isIdle: boolean;

#### isLoading

ts

isLoading: boolean;


isLoading: boolean;

#### isReady

ts

isReady: boolean;


isReady: boolean;

#### state

ts

state: Map<string | number, { [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] }>;


state: Map<string | number, { [K in string | number | symbol]: (TContext["result"] extends object ? any[any] : TContext["hasJoins"] extends true ? TContext["schema"] : TContext["schema"][TContext["fromSourceName"]])[K] }>;

#### status

ts

status: CollectionStatus;


status: CollectionStatus;

### Examples

ts

// Basic config object usage
const { data, status } = useLiveQuery({
  query: (q) => q.from({ todos: todosCollection }),
  gcTime: 60000
})


// Basic config object usage
const { data, status } = useLiveQuery({
  query: (q) => q.from({ todos: todosCollection }),
  gcTime: 60000
})

ts

// With query builder and options
const queryBuilder = new Query()
  .from({ persons: collection })
  .where(({ persons }) => gt(persons.age, 30))
  .select(({ persons }) => ({ id: persons.id, name: persons.name }))

const { data, isReady } = useLiveQuery({ query: queryBuilder })


// With query builder and options
const queryBuilder = new Query()
  .from({ persons: collection })
  .where(({ persons }) => gt(persons.age, 30))
  .select(({ persons }) => ({ id: persons.id, name: persons.name }))

const { data, isReady } = useLiveQuery({ query: queryBuilder })

ts

// Handle all states uniformly
const { data, isLoading, isReady, isError } = useLiveQuery({
  query: (q) => q.from({ items: itemCollection })
})

if (isLoading) return <div>Loading...</div>
if (isError) return <div>Something went wrong</div>
if (!isReady) return <div>Preparing...</div>

return <div>{data.length} items loaded</div>


// Handle all states uniformly
const { data, isLoading, isReady, isError } = useLiveQuery({
  query: (q) => q.from({ items: itemCollection })
})

if (isLoading) return <div>Loading...</div>
if (isError) return <div>Something went wrong</div>
if (!isReady) return <div>Preparing...</div>

return <div>{data.length} items loaded</div>

Call Signature
--------------

ts

function useLiveQuery<TResult, TKey, TUtils>(liveQueryCollection): object;


function useLiveQuery<TResult, TKey, TUtils>(liveQueryCollection): object;

Defined in: useLiveQuery.ts:276

Subscribe to an existing live query collection

### 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

Pre-created live query collection to subscribe to

### Returns

object

Object with reactive data, state, and status information

#### collection

ts

collection: Collection<TResult, TKey, TUtils>;


collection: Collection<TResult, TKey, TUtils>;

#### data

ts

data: TResult[];


data: TResult[];

#### isCleanedUp

ts

isCleanedUp: boolean;


isCleanedUp: boolean;

#### isEnabled

ts

isEnabled: true;


isEnabled: true;

#### isError

ts

isError: boolean;


isError: boolean;

#### isIdle

ts

isIdle: boolean;


isIdle: boolean;

#### isLoading

ts

isLoading: boolean;


isLoading: boolean;

#### isReady

ts

isReady: boolean;


isReady: boolean;

#### state

ts

state: Map<TKey, TResult>;


state: Map<TKey, TResult>;

#### status

ts

status: CollectionStatus;


status: CollectionStatus;

### Examples

ts

// Using pre-created live query collection
const myLiveQuery = createLiveQueryCollection((q) =>
  q.from({ todos: todosCollection }).where(({ todos }) => eq(todos.active, true))
)
const { data, collection } = useLiveQuery(myLiveQuery)


// Using pre-created live query collection
const myLiveQuery = createLiveQueryCollection((q) =>
  q.from({ todos: todosCollection }).where(({ todos }) => eq(todos.active, true))
)
const { data, collection } = useLiveQuery(myLiveQuery)

ts

// Access collection methods directly
const { data, collection, isReady } = useLiveQuery(existingCollection)

// Use collection for mutations
const handleToggle = (id) => {
  collection.update(id, draft => { draft.completed = !draft.completed })
}


// Access collection methods directly
const { data, collection, isReady } = useLiveQuery(existingCollection)

// Use collection for mutations
const handleToggle = (id) => {
  collection.update(id, draft => { draft.completed = !draft.completed })
}

ts

// Handle states consistently
const { data, isLoading, isError } = useLiveQuery(sharedCollection)

if (isLoading) return <div>Loading...</div>
if (isError) return <div>Error loading data</div>

return <div>{data.map(item => <Item key={item.id} {...item} />)}</div>


// Handle states consistently
const { data, isLoading, isError } = useLiveQuery(sharedCollection)

if (isLoading) return <div>Loading...</div>
if (isError) return <div>Error loading data</div>

return <div>{data.map(item => <Item key={item.id} {...item} />)}</div>

Call Signature
--------------

ts

function useLiveQuery<TResult, TKey, TUtils>(liveQueryCollection): object;


function useLiveQuery<TResult, TKey, TUtils>(liveQueryCollection): object;

Defined in: useLiveQuery.ts:296

Create a live query using a query function

### 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

object

Object with reactive data, state, and status information

#### collection

ts

collection: Collection<TResult, TKey, TUtils, StandardSchemaV1<unknown, unknown>, TResult> & SingleResult;


collection: Collection<TResult, TKey, TUtils, StandardSchemaV1<unknown, unknown>, TResult> & SingleResult;

#### data

ts

data: TResult | undefined;


data: TResult | undefined;

#### isCleanedUp

ts

isCleanedUp: boolean;


isCleanedUp: boolean;

#### isEnabled

ts

isEnabled: true;


isEnabled: true;

#### isError

ts

isError: boolean;


isError: boolean;

#### isIdle

ts

isIdle: boolean;


isIdle: boolean;

#### isLoading

ts

isLoading: boolean;


isLoading: boolean;

#### isReady

ts

isReady: boolean;


isReady: boolean;

#### state

ts

state: Map<TKey, TResult>;


state: Map<TKey, TResult>;

#### status

ts

status: CollectionStatus;


status: CollectionStatus;

### Examples

ts

// Basic query with object syntax
const { data, isLoading } = useLiveQuery((q) =>
  q.from({ todos: todosCollection })
   .where(({ todos }) => eq(todos.completed, false))
   .select(({ todos }) => ({ id: todos.id, text: todos.text }))
)


// Basic query with object syntax
const { data, isLoading } = useLiveQuery((q) =>
  q.from({ todos: todosCollection })
   .where(({ todos }) => eq(todos.completed, false))
   .select(({ todos }) => ({ id: todos.id, text: todos.text }))
)

ts

// Single result query
const { data } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)


// Single result query
const { data } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)

ts

// With dependencies that trigger re-execution
const { data, state } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [minPriority] // Re-run when minPriority changes
)


// With dependencies that trigger re-execution
const { data, state } = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [minPriority] // Re-run when minPriority changes
)

ts

// Join pattern
const { data } = useLiveQuery((q) =>
  q.from({ issues: issueCollection })
   .join({ persons: personCollection }, ({ issues, persons }) =>
     eq(issues.userId, persons.id)
   )
   .select(({ issues, persons }) => ({
     id: issues.id,
     title: issues.title,
     userName: persons.name
   }))
)


// Join pattern
const { data } = useLiveQuery((q) =>
  q.from({ issues: issueCollection })
   .join({ persons: personCollection }, ({ issues, persons }) =>
     eq(issues.userId, persons.id)
   )
   .select(({ issues, persons }) => ({
     id: issues.id,
     title: issues.title,
     userName: persons.name
   }))
)

ts

// Handle loading and error states
const { data, isLoading, isError, status } = useLiveQuery((q) =>
  q.from({ todos: todoCollection })
)

if (isLoading) return <div>Loading...</div>
if (isError) return <div>Error: {status}</div>

return (
  <ul>
    {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
  </ul>
)


// Handle loading and error states
const { data, isLoading, isError, status } = useLiveQuery((q) =>
  q.from({ todos: todoCollection })
)

if (isLoading) return <div>Loading...</div>
if (isError) return <div>Error: {status}</div>

return (
  <ul>
    {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
  </ul>
)

Edit on GitHub

React Hooks

Partners Become a Partner

Code RabbitCode Rabbit CloudflareCloudflare AG GridAG Grid NetlifyNetlify NeonNeon WorkOSWorkOS ClerkClerk ConvexConvex ElectricElectric SentrySentry PrismaPrisma StrapiStrapi UnkeyUnkey

scarf analytics