Skip to content
Source
Sign inSign up
TanStack/form
Open History to see the last commit

async-initial-values.md

160 lines4.6 KB

Forms often edit data loaded from an API. A server-state library such as TanStack Query should own fetching, caching, loading, and retries; TanStack Form should own the editable copy.

There are two supported ways to provide async initial values: wait to create the form until the data is ready, or create it immediately with complete fallback values. Choose the approach that best matches the loading experience your UI needs.

Wait for data before creating the editor

Render a loading or error state first, then mount a component whose defaultValues are complete.

// UserPage.tsx
import { Show } from 'solid-js'
import { createQuery } from '@tanstack/solid-query'
import { UserEditor } from './UserEditor'
import type { User } from './types'

export function UserPage(props: { userId: string }) {
  const userQuery = createQuery(() => ({
    queryKey: ['user', props.userId],
    queryFn: async (): Promise<User> => {
      const response = await fetch(`/api/users/${props.userId}`)
      return response.json()
    },
  }))

  return (
    <Show
      when={!userQuery.isError}
      fallback={<p role="alert">Could not load the user.</p>}
    >
      <Show when={userQuery.data} keyed fallback={<p>Loading…</p>}>
        {(user) => <UserEditor user={user} />}
      </Show>
    </Show>
  )
}
// UserEditor.tsx
import { createForm } from '@tanstack/solid-form'
import type { User } from './types'

export function UserEditor(props: { user: User }) {
  const form = createForm(() => ({
    defaultValues: props.user,
    onSubmit: async ({ value }) => {
      await fetch('/api/users', {
        method: 'PUT',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify(value),
      })
    },
  }))

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault()
        form.handleSubmit()
      }}
    >
      {/* fields */}
    </form>
  )
}

This pattern is useful when no form state is needed during loading. The keyed Show recreates the editor when a different user object arrives.

Create the form before data arrives

You can instead call createForm in the same component as createQuery. Provide a static, shape-complete fallback so defaultValues are never undefined.

import { Show } from 'solid-js'
import { createQuery } from '@tanstack/solid-query'
import { createForm } from '@tanstack/solid-form'
import type { User } from './types'

const emptyUser: User = {
  firstName: '',
  lastName: '',
}

export function UserPage(props: { userId: string }) {
  const userQuery = createQuery(() => ({
    queryKey: ['user', props.userId],
    queryFn: async (): Promise<User> => {
      const response = await fetch(`/api/users/${props.userId}`)
      return response.json()
    },
  }))

  const form = createForm(() => ({
    defaultValues: userQuery.data ?? emptyUser,
    onSubmit: async ({ value }) => {
      await fetch('/api/users', {
        method: 'PUT',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify(value),
      })
    },
  }))

  return (
    <Show
      when={!userQuery.isError}
      fallback={<p role="alert">Could not load the user.</p>}
    >
      <Show when={!userQuery.isPending} fallback={<p>Loading…</p>}>
        <form
          onSubmit={(event) => {
            event.preventDefault()
            form.handleSubmit()
          }}
        >
          {/* fields */}
        </form>
      </Show>
    </Show>
  )
}

Because both integrations receive accessors, reading userQuery.data inside the form options accessor keeps the options reactive. When query data replaces the fallback, TanStack Form applies the new defaultValues to untouched fields while preserving fields the user has already touched.

This is the approach demonstrated by the repository's examples/solid/query-integration example.

Background refetches and record changes

defaultValues establish the form's baseline; they are not a fully controlled values prop. In the fallback pattern, later defaultValues updates use the same touched-field-preserving behavior.

If background refetches arrive while a user is editing, decide at the product level whether to keep local edits, prompt before replacing them, or call form.reset(nextValues) deliberately. Do not overwrite in-progress input merely because a query refreshed.

When switching to a different record, either recreate a keyed editor as in the first pattern or deliberately reset the existing form. Otherwise, touched values from the previous record can be preserved when the new defaults arrive.