createQuery

Call Signature

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

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

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

svelte

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

svelte

<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, queryClient?): DefinedCreateQueryResult<TData, TError>;

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

This overload is selected when initialData is set, so the resulting data is never 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

svelte

<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, queryClient?): CreateQueryResult<TData, TError>;

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

Type Parameters

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>

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:

svelte

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

svelte

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

svelte

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

svelte

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