createQuery

Overview#

function createQuery<TQueryFnData, TError, TData, TQueryKey>(options: Accessor<DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>>, queryClient?: Accessor<QueryClient>): DefinedCreateQueryResult<TData, TError>;
function createQuery<TQueryFnData, TError, TData, TQueryKey>(options: Accessor<UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>>, queryClient?: Accessor<QueryClient>): CreateQueryResult<TData, TError>;
function createQuery<TQueryFnData, TError, TData, TQueryKey>(options: Accessor<CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey>>, queryClient?: Accessor<QueryClient>): CreateQueryResult<TData, TError>;

• DefinedInitialDataOptions → DefinedCreateQueryResult: Subscribes to a query: a declarative dependency on an asynchronous source of data that is tied to a unique key. The query runs when the options call for it — enabled: false skips the initial fetch.
• UndefinedInitialDataOptions → CreateQueryResult: Subscribes to a query: a declarative dependency on an asynchronous source of data that is tied to a unique key. The query runs when the options call for it — enabled: false skips the initial fetch.
• CreateQueryOptions → CreateQueryResult: Fallback overload for options whose initialData presence isn't statically known — for example, an object typed as CreateQueryOptions rather than an object literal. Prefer one of the other overloads when possible, since they infer whether data can be undefined from initialData directly.

See also: Parameters · Returns

Call Signature#

function createQuery<TQueryFnData, TError, TData, TQueryKey>(options: Accessor<DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>>, queryClient?: Accessor<QueryClient>): DefinedCreateQueryResult<TData, TError>;

Defined in: packages/svelte-query/src/createQuery.ts:53

Subscribes to a query: a declarative dependency on an asynchronous source of data that is tied to a unique key. The query runs when the options call for it — enabled: false skips the initial fetch.

This overload is selected when initialData is set, so the resulting data is never undefined (unless a select changes TData to include undefined).

Type Parameters#

TQueryFnData#

TQueryFnData = unknown

TError#

TError = Error

TData#

TData = TQueryFnData

TQueryKey#

TQueryKey extends readonly unknown[] = readonly unknown[]

Parameters#

options#

Accessor<DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>>

The DefinedInitialDataOptions to use — everything you can pass to createQuery, with initialData set, wrapped in an Accessor so options can be reactive.

queryClient?#

Accessor<QueryClient>

Use this to use a custom QueryClient. Otherwise, the one from the nearest context will be used.

Returns#

DefinedCreateQueryResult<TData, TError>

The current query result, typed so that status is success — or error if a fetch attempt fails while keeping the existing data (status never resolves to pending in this overload's type, since initialData guarantees data upfront). isSuccess/isError are derived booleans for convenience.

See#

queryOptions to share these options between createQuery and imperative APIs like queryClient.query.

Example#

<script lang="ts">
  import { createQuery } from '@tanstack/svelte-query'

  // `data` is `Post[]`, never `undefined`, thanks to `initialData` — even if a refetch fails,
  // so the list stays visible alongside the error.
  const query = createQuery(() => ({
    queryKey: ['posts'],
    queryFn: fetchPosts,
    initialData: [],
  }))
</script>

{#if query.isError}
  <span>Error: {query.error.message}</span>
{/if}
<ul>
  {#each query.data as post (post.id)}
    <li>{post.title}</li>
  {/each}
</ul>

Call Signature#

function createQuery<TQueryFnData, TError, TData, TQueryKey>(options: Accessor<UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>>, queryClient?: Accessor<QueryClient>): CreateQueryResult<TData, TError>;

Defined in: packages/svelte-query/src/createQuery.ts:124

Subscribes to a query: a declarative dependency on an asynchronous source of data that is tied to a unique key. The query runs when the options call for it — enabled: false skips the initial fetch.

Type Parameters#

TQueryFnData#

TQueryFnData = unknown

TError#

TError = Error

TData#

TData = TQueryFnData

TQueryKey#

TQueryKey extends readonly unknown[] = readonly unknown[]

Parameters#

options#

Accessor<UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>>

The UndefinedInitialDataOptions to use — everything you can pass to createQuery, wrapped in an Accessor so options can be reactive.

queryClient?#

Accessor<QueryClient>

Use this to use a custom QueryClient. Otherwise, the one from the nearest context will be used.

Returns#

CreateQueryResult<TData, TError>

The current query result. status is pending if there is no cached data to display, error if the last fetch attempt failed, or success if the query has data to display. isPending/isSuccess/isError are derived booleans for convenience.

See#

queryOptions to share these options between createQuery and imperative APIs like queryClient.query.

Examples#

<script lang="ts">
  import { createQuery } from '@tanstack/svelte-query'

  const query = createQuery(() => ({
    queryKey: ['posts'],
    queryFn: fetchPosts,
  }))
</script>

{#if query.status === 'pending'}
  Loading...
{:else if query.status === 'error'}
  <span>Error: {query.error.message}</span>
{:else}
  <ul>
    {#each query.data as post (post.id)}
      <li>{post.title}</li>
    {/each}
  </ul>
{/if}

The same query, checking isPending/isError instead of status — pick whichever reads better to you:

<script lang="ts">
  import { createQuery } from '@tanstack/svelte-query'

  const query = createQuery(() => ({
    queryKey: ['posts'],
    queryFn: fetchPosts,
  }))
</script>

{#if query.isPending}
  Loading...
{:else if query.isError}
  <span>Error: {query.error.message}</span>
{:else}
  <ul>
    {#each query.data as post (post.id)}
      <li>{post.title}</li>
    {/each}
  </ul>
{/if}

Call Signature#

function createQuery<TQueryFnData, TError, TData, TQueryKey>(options: Accessor<CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey>>, queryClient?: Accessor<QueryClient>): CreateQueryResult<TData, TError>;

Defined in: packages/svelte-query/src/createQuery.ts:249

Fallback overload for options whose initialData presence isn't statically known — for example, an object typed as CreateQueryOptions rather than an object literal. Prefer one of the other overloads when possible, since they infer whether data can be undefined from initialData directly.

Type Parameters#

TQueryFnData#

TQueryFnData

TError#

TError = Error

TData#

TData = TQueryFnData

TQueryKey#

TQueryKey extends readonly unknown[] = readonly unknown[]

Parameters#

options#

Accessor<CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey>>

The CreateQueryOptions to use — everything you can pass to createQuery, wrapped in an Accessor so options can be reactive.

queryClient?#

Accessor<QueryClient>

Use this to use a custom QueryClient. Otherwise, the one from the nearest context will be used.

Returns#

CreateQueryResult<TData, TError>

The current query result. status is pending if there is no cached data to display, error if the last fetch attempt failed, or success if the query has data to display. isPending/isSuccess/isError are derived booleans for convenience.

See#

queryOptions to share these options between createQuery and imperative APIs like queryClient.query.

Examples#

select derives whatever data a component needs from the cached value, without changing what's actually stored in the cache — the cache still holds the full Post[], but data here is a number:

<script lang="ts">
  import { createQuery } from '@tanstack/svelte-query'

  const query = createQuery(() => ({
    queryKey: ['posts'],
    queryFn: fetchPosts,
    select: (posts) => posts.length,
  }))
</script>

{#if query.isPending}
  Loading...
{:else if query.isError}
  <span>Error: {query.error.message}</span>
{:else}
  <span>{query.data} posts</span>
{/if}

A dependent query, only enabled once postId is set — use isLoading, not isPending, so the loading state doesn't show while the query is disabled:

<script lang="ts">
  import { createQuery } from '@tanstack/svelte-query'

  let { postId }: { postId: number | undefined } = $props()

  const query = createQuery(() => ({
    queryKey: ['post', postId],
    queryFn: () => fetchPost(postId!),
    enabled: postId != null,
  }))
</script>

{#if postId == null}
  Select a post
{:else if query.isLoading}
  Loading...
{:else if query.isError}
  <span>Error: {query.error.message}</span>
{:else}
  <h1>{query.data?.title}</h1>
{/if}

Seeding a detail query from an already-cached list, to skip the loading state:

<script lang="ts">
  import { createQuery, useQueryClient } from '@tanstack/svelte-query'

  let { postId }: { postId: number } = $props()

  const queryClient = useQueryClient()

  const query = createQuery(() => ({
    queryKey: ['post', postId],
    queryFn: () => fetchPost(postId),
    initialData: () =>
      queryClient
        .getQueryData<Array<Post>>(['posts'])
        ?.find((post) => post.id === postId),
  }))
</script>

{#if query.isError}
  <span>Error: {query.error.message}</span>
{/if}
<h1>{query.data?.title}</h1>

Paginated data, keeping the previous page's data visible while the next page loads:

<script lang="ts">
  import { createQuery, keepPreviousData } from '@tanstack/svelte-query'

  let page = $state(0)

  const query = createQuery(() => ({
    queryKey: ['posts', page],
    queryFn: () => fetchPosts(page),
    placeholderData: keepPreviousData,
  }))
</script>

{#if query.isError}
  <span>Error: {query.error.message}</span>
{/if}
<ul>
  {#each query.data ?? [] as post (post.id)}
    <li>{post.title}</li>
  {/each}
</ul>
<button disabled={query.isPlaceholderData} onclick={() => page++}>
  Next Page
</button>

Parameters#

options#

Accessor<CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey>>

The CreateQueryOptions to use — everything you can pass to createQuery, wrapped in an Accessor so options can be reactive.

options properties#

queryClient?#

Accessor<QueryClient>

Use this to use a custom QueryClient. Otherwise, the one from the nearest context will be used.

Returns#

CreateQueryResult<TData, TError>

The current query result. status is pending if there is no cached data to display, error if the last fetch attempt failed, or success if the query has data to display. isPending/isSuccess/isError are derived booleans for convenience.

Result properties#