TanStack
DB v0v0
Documentation
Framework
Version
Menu
Getting Started
Guides
Collections
Community
API Reference

useLiveSuspenseQuery

Function: useLiveSuspenseQuery()

Call Signature
ts
function useLiveSuspenseQuery<TContext>(queryFn, deps?): object;

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

Defined in: useLiveSuspenseQuery.ts:76

Create a live query with React Suspense support

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 and state - data is guaranteed to be defined

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

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] }>;

Throws

Promise when data is loading (caught by Suspense boundary)

Throws

Error when collection fails (caught by Error boundary)

Examples
ts
// Basic usage with Suspense
function TodoList() {
  const { data } = useLiveSuspenseQuery((q) =>
    q.from({ todos: todosCollection })
     .where(({ todos }) => eq(todos.completed, false))
     .select(({ todos }) => ({ id: todos.id, text: todos.text }))
  )

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

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <TodoList />
    </Suspense>
  )
}

// Basic usage with Suspense
function TodoList() {
  const { data } = useLiveSuspenseQuery((q) =>
    q.from({ todos: todosCollection })
     .where(({ todos }) => eq(todos.completed, false))
     .select(({ todos }) => ({ id: todos.id, text: todos.text }))
  )

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

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <TodoList />
    </Suspense>
  )
}
ts
// Single result query
const { data } = useLiveSuspenseQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)
// data is guaranteed to be the single item (or undefined if not found)

// Single result query
const { data } = useLiveSuspenseQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)
// data is guaranteed to be the single item (or undefined if not found)
ts
// With dependencies that trigger re-suspension
const { data } = useLiveSuspenseQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [minPriority] // Re-suspends when minPriority changes
)

// With dependencies that trigger re-suspension
const { data } = useLiveSuspenseQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [minPriority] // Re-suspends when minPriority changes
)
ts
// With Error boundary
function App() {
  return (
    <ErrorBoundary fallback={<div>Error loading data</div>}>
      <Suspense fallback={<div>Loading...</div>}>
        <TodoList />
      </Suspense>
    </ErrorBoundary>
  )
}

// With Error boundary
function App() {
  return (
    <ErrorBoundary fallback={<div>Error loading data</div>}>
      <Suspense fallback={<div>Loading...</div>}>
        <TodoList />
      </Suspense>
    </ErrorBoundary>
  )
}

Call Signature
ts
function useLiveSuspenseQuery<TContext>(config, deps?): object;

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

Defined in: useLiveSuspenseQuery.ts:86

Create a live query with React Suspense support

Type Parameters

TContext

TContext extends Context

Parameters

config

LiveQueryCollectionConfig<TContext>

deps?

unknown[]

Array of dependencies that trigger query re-execution when changed

Returns

object

Object with reactive data and state - data is guaranteed to be defined

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

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] }>;

Throws

Promise when data is loading (caught by Suspense boundary)

Throws

Error when collection fails (caught by Error boundary)

Examples
ts
// Basic usage with Suspense
function TodoList() {
  const { data } = useLiveSuspenseQuery((q) =>
    q.from({ todos: todosCollection })
     .where(({ todos }) => eq(todos.completed, false))
     .select(({ todos }) => ({ id: todos.id, text: todos.text }))
  )

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

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <TodoList />
    </Suspense>
  )
}

// Basic usage with Suspense
function TodoList() {
  const { data } = useLiveSuspenseQuery((q) =>
    q.from({ todos: todosCollection })
     .where(({ todos }) => eq(todos.completed, false))
     .select(({ todos }) => ({ id: todos.id, text: todos.text }))
  )

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

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <TodoList />
    </Suspense>
  )
}
ts
// Single result query
const { data } = useLiveSuspenseQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)
// data is guaranteed to be the single item (or undefined if not found)

// Single result query
const { data } = useLiveSuspenseQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)
// data is guaranteed to be the single item (or undefined if not found)
ts
// With dependencies that trigger re-suspension
const { data } = useLiveSuspenseQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [minPriority] // Re-suspends when minPriority changes
)

// With dependencies that trigger re-suspension
const { data } = useLiveSuspenseQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [minPriority] // Re-suspends when minPriority changes
)
ts
// With Error boundary
function App() {
  return (
    <ErrorBoundary fallback={<div>Error loading data</div>}>
      <Suspense fallback={<div>Loading...</div>}>
        <TodoList />
      </Suspense>
    </ErrorBoundary>
  )
}

// With Error boundary
function App() {
  return (
    <ErrorBoundary fallback={<div>Error loading data</div>}>
      <Suspense fallback={<div>Loading...</div>}>
        <TodoList />
      </Suspense>
    </ErrorBoundary>
  )
}

Call Signature
ts
function useLiveSuspenseQuery<TResult, TKey, TUtils>(liveQueryCollection): object;

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

Defined in: useLiveSuspenseQuery.ts:96

Create a live query with React Suspense support

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

object

Object with reactive data and state - data is guaranteed to be defined

collection
ts
collection: Collection<TResult, TKey, TUtils>;

collection: Collection<TResult, TKey, TUtils>;

data
ts
data: TResult[];

data: TResult[];

state
ts
state: Map<TKey, TResult>;

state: Map<TKey, TResult>;

Throws

Promise when data is loading (caught by Suspense boundary)

Throws

Error when collection fails (caught by Error boundary)

Examples
ts
// Basic usage with Suspense
function TodoList() {
  const { data } = useLiveSuspenseQuery((q) =>
    q.from({ todos: todosCollection })
     .where(({ todos }) => eq(todos.completed, false))
     .select(({ todos }) => ({ id: todos.id, text: todos.text }))
  )

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

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <TodoList />
    </Suspense>
  )
}

// Basic usage with Suspense
function TodoList() {
  const { data } = useLiveSuspenseQuery((q) =>
    q.from({ todos: todosCollection })
     .where(({ todos }) => eq(todos.completed, false))
     .select(({ todos }) => ({ id: todos.id, text: todos.text }))
  )

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

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <TodoList />
    </Suspense>
  )
}
ts
// Single result query
const { data } = useLiveSuspenseQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)
// data is guaranteed to be the single item (or undefined if not found)

// Single result query
const { data } = useLiveSuspenseQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)
// data is guaranteed to be the single item (or undefined if not found)
ts
// With dependencies that trigger re-suspension
const { data } = useLiveSuspenseQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [minPriority] // Re-suspends when minPriority changes
)

// With dependencies that trigger re-suspension
const { data } = useLiveSuspenseQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [minPriority] // Re-suspends when minPriority changes
)
ts
// With Error boundary
function App() {
  return (
    <ErrorBoundary fallback={<div>Error loading data</div>}>
      <Suspense fallback={<div>Loading...</div>}>
        <TodoList />
      </Suspense>
    </ErrorBoundary>
  )
}

// With Error boundary
function App() {
  return (
    <ErrorBoundary fallback={<div>Error loading data</div>}>
      <Suspense fallback={<div>Loading...</div>}>
        <TodoList />
      </Suspense>
    </ErrorBoundary>
  )
}

Call Signature
ts
function useLiveSuspenseQuery<TResult, TKey, TUtils>(liveQueryCollection): object;

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

Defined in: useLiveSuspenseQuery.ts:109

Create a live query with React Suspense support

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 and state - data is guaranteed to be defined

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;

state
ts
state: Map<TKey, TResult>;

state: Map<TKey, TResult>;

Throws

Promise when data is loading (caught by Suspense boundary)

Throws

Error when collection fails (caught by Error boundary)

Examples
ts
// Basic usage with Suspense
function TodoList() {
  const { data } = useLiveSuspenseQuery((q) =>
    q.from({ todos: todosCollection })
     .where(({ todos }) => eq(todos.completed, false))
     .select(({ todos }) => ({ id: todos.id, text: todos.text }))
  )

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

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <TodoList />
    </Suspense>
  )
}

// Basic usage with Suspense
function TodoList() {
  const { data } = useLiveSuspenseQuery((q) =>
    q.from({ todos: todosCollection })
     .where(({ todos }) => eq(todos.completed, false))
     .select(({ todos }) => ({ id: todos.id, text: todos.text }))
  )

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

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <TodoList />
    </Suspense>
  )
}
ts
// Single result query
const { data } = useLiveSuspenseQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)
// data is guaranteed to be the single item (or undefined if not found)

// Single result query
const { data } = useLiveSuspenseQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
)
// data is guaranteed to be the single item (or undefined if not found)
ts
// With dependencies that trigger re-suspension
const { data } = useLiveSuspenseQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [minPriority] // Re-suspends when minPriority changes
)

// With dependencies that trigger re-suspension
const { data } = useLiveSuspenseQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
  [minPriority] // Re-suspends when minPriority changes
)
ts
// With Error boundary
function App() {
  return (
    <ErrorBoundary fallback={<div>Error loading data</div>}>
      <Suspense fallback={<div>Loading...</div>}>
        <TodoList />
      </Suspense>
    </ErrorBoundary>
  )
}

// With Error boundary
function App() {
  return (
    <ErrorBoundary fallback={<div>Error loading data</div>}>
      <Suspense fallback={<div>Loading...</div>}>
        <TodoList />
      </Suspense>
    </ErrorBoundary>
  )
}
Edit on GitHub
Home
Partners
Code Rabbit
Cloudflare
AG Grid
Netlify
Neon
WorkOS
Clerk
Convex
Electric
Sentry
Prisma
Strapi
Unkey
Subscribe to Bytes

Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.

Bytes

No spam. Unsubscribe at any time.

Subscribe to Bytes

Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.

Bytes

No spam. Unsubscribe at any time.