TanStack Form

A thin integration layer that wires TanStack Form to Pindoba controls. It builds on the presentational Field wrapper — Field owns the label, description, tooltip, error region, accessibility wiring, and validation-driven feedback color; this block adds the form state, validation, and value binding on top.

It ships ready-made <FormInput>, <FormSelect>, and <FormCheckbox> wrappers for the common controls, a generic <FormField> escape hatch for everything else, and a <FormSubmit> button that disables while a submission is in flight (and, opt-in, while the form is invalid). The package re-exports TanStack’s createForm, so you import everything from one place.

Available for Svelte, React, and Astro. All build on the same agnostic core (@pindoba/core-tanstack-form) over @tanstack/form-core; the wrappers and error/feedback behavior are identical.

They differ only in how you create the form, because TanStack Form is client-reactive and Astro has no runtime reactivity:

Svelte — createForm(...) (re-exported from the block) and pass the instance to each wrapper via form={...}.
React — useForm(...) (re-exported from the block) and pass the instance to each wrapper via form={...}.
Astro — wrap the controls in <pindoba-form> and create the form in a client <script> (new FormApi(...)), then assign it to the element’s .form property. Validators and onSubmit aren’t serializable, so the form definition lives in script, not markup. The custom element wires every field via bindForm and re-binds across view transitions automatically. (Prefer the lower-level bindForm(rootEl, form) directly if you’re not using the element.)

Quick start

createForm / new FormApi accept Standard Schema validators natively — Zod 3.24+, Valibot, and ArkType all work without any adapter. Pass one under validators.onChange (or onBlur / onSubmit) and the matching field messages flow straight into each control’s error region. Toggle the demo’s Code view for the full source — including the Astro client <script> that builds the form.

AstroReactSvelteVueTODO

PreviewCode

Name

---
import { stack } from "@pindoba/styled-system/patterns";
import FormInput from "../FormInput.astro";
import FormSubmit from "../FormSubmit.astro";
---

<pindoba-form id="tsf-basic">
  <div class={stack({ gap: "md", direction: "column" })}>
    <FormInput name="name" label="Name" required />
    <FormInput name="email" label="Email" type="email" required />
    <FormSubmit>Create account</FormSubmit>
    <p data-form-result hidden></p>
  </div>
</pindoba-form>

<script>
  import "../pindoba-form";
  import type { PindobaFormElement } from "../pindoba-form";
  import { FormApi } from "@tanstack/form-core";
  import { z } from "zod";

  // `@tanstack/form-core` accepts Standard Schema validators natively — Zod
  // 3.24+, Valibot, ArkType all work with no adapter.
  const schema = z.object({
    name: z.string().min(2, "Use at least 2 characters."),
    email: z.string().email("Enter a valid email address."),
  });

  const root = document.querySelector<PindobaFormElement>("#tsf-basic");
  const result = root?.querySelector<HTMLElement>("[data-form-result]");

  const form = new FormApi({
    defaultValues: { name: "", email: "" },
    validators: { onChange: schema },
    onSubmit: async ({ value }) => {
      if (result) {
        result.textContent = `Submitted: ${JSON.stringify(value)}`;
        result.hidden = false;
      }
    },
  });
  form.mount();
  if (root) root.form = form;
</script>

import { stack } from "@pindoba/styled-system/patterns";
import { useState } from "react";
import { z } from "zod";
import {
  FormInput,
  FormSubmit,
  useForm,
  useFocusInvalidOnSubmit,
} from "../../index";

const schema = z.object({
  name: z.string().min(2, "Use at least 2 characters."),
  email: z.string().email("Enter a valid email address."),
});

export default function BasicDemo() {
  const [submitted, setSubmitted] = useState<string | null>(null);

  const form = useForm({
    defaultValues: { name: "", email: "" },
    validators: { onChange: schema },
    onSubmit: async ({ value }) => {
      setSubmitted(JSON.stringify(value));
    },
  });

  const formRef = useFocusInvalidOnSubmit(form);

  return (
    <form
      ref={formRef}
      onSubmit={(event) => {
        event.preventDefault();
        form.handleSubmit();
      }}
    >
      <div className={stack({ gap: "md", direction: "column" })}>
        <FormInput form={form} name="name" label="Name" required />
        <FormInput
          form={form}
          name="email"
          label="Email"
          type="email"
          required
          labelTooltip="We email your receipt here."
        />
        <FormSubmit form={form}>Create account</FormSubmit>
        {submitted && <p>Submitted: {submitted}</p>}
      </div>
    </form>
  );
}

<script lang="ts">
  import { z } from "zod";
  import {
    createForm,
    FormInput,
    FormSubmit,
    focusInvalidOnSubmit,
  } from "../index.js";
  import { stack } from "@pindoba/styled-system/patterns";

  const schema = z.object({
    name: z.string().min(2, "Use at least 2 characters."),
    email: z.string().email("Enter a valid email address."),
  });

  let submitted = $state<string | null>(null);

  const form = createForm(() => ({
    defaultValues: { name: "", email: "" },
    validators: { onChange: schema },
    onSubmit: async ({ value }) => {
      submitted = JSON.stringify(value);
    },
  }));
</script>

<form
  onsubmit={(event) => {
    event.preventDefault();
    form.handleSubmit();
  }}
  {@attach focusInvalidOnSubmit(form)}
>
  <div class={stack({ gap: "md", direction: "column" })}>
    <FormInput {form} name="name" label="Name" required />
    <FormInput
      {form}
      name="email"
      label="Email"
      type="email"
      required
      labelTooltip="We email your receipt here."
    />
    <FormSubmit {form}>Create account</FormSubmit>
    {#if submitted}<p>Submitted: {submitted}</p>{/if}
  </div>
</form>

Control wrappers

<FormInput>, <FormSelect>, and <FormCheckbox> each bind a control to a form field and forward every Field prop (label, description, required, labelTooltip, size, orientation, feedback, errorMode, …). Errors flip the control to the danger feedback color automatically.

AstroReactSvelteVueTODO

PreviewCode

Full name

Country

Select a country

Agreement

I accept the terms of service

---
import { stack } from "@pindoba/styled-system/patterns";
import FormInput from "../FormInput.astro";
import FormSelect from "../FormSelect.astro";
import FormCheckbox from "../FormCheckbox.astro";
import FormSubmit from "../FormSubmit.astro";

const countries = [
  { id: "br", label: "Brazil" },
  { id: "us", label: "United States" },
  { id: "pt", label: "Portugal" },
];
---

<pindoba-form id="tsf-mixed">
  <div class={stack({ gap: "md", direction: "column" })}>
    <FormInput name="fullName" label="Full name" required />
    <FormSelect
      name="country"
      label="Country"
      items={countries}
      placeholder="Select a country"
      required
    />
    <FormCheckbox name="terms" label="Agreement" errorMode="submitted">
      I accept the terms of service
    </FormCheckbox>
    <FormSubmit>Continue</FormSubmit>
    <p data-form-result hidden></p>
  </div>
</pindoba-form>

<script>
  import "../pindoba-form";
  import type { PindobaFormElement } from "../pindoba-form";
  import { FormApi } from "@tanstack/form-core";
  import { z } from "zod";

  const schema = z.object({
    fullName: z.string().min(2, "Use at least 2 characters."),
    country: z.string().min(1, "Pick a country."),
    terms: z.literal(true, { message: "You must accept the terms." }),
  });

  const root = document.querySelector<PindobaFormElement>("#tsf-mixed");
  const result = root?.querySelector<HTMLElement>("[data-form-result]");

  const form = new FormApi({
    defaultValues: { fullName: "", country: "", terms: false },
    validators: { onChange: schema },
    onSubmit: async ({ value }) => {
      if (result) {
        result.textContent = `Submitted: ${JSON.stringify(value)}`;
        result.hidden = false;
      }
    },
  });
  form.mount();
  if (root) root.form = form;
</script>

import { stack } from "@pindoba/styled-system/patterns";
import { useState } from "react";
import { z } from "zod";
import {
  FormCheckbox,
  FormInput,
  FormSelect,
  FormSubmit,
  useForm,
  useFocusInvalidOnSubmit,
} from "../../index";

const countries = [
  { id: "br", label: "Brazil" },
  { id: "us", label: "United States" },
  { id: "pt", label: "Portugal" },
];

const schema = z.object({
  fullName: z.string().min(2, "Use at least 2 characters."),
  country: z.string().min(1, "Pick a country."),
  terms: z.literal(true, { message: "You must accept the terms." }),
});

export default function MixedControlsDemo() {
  const [submitted, setSubmitted] = useState<string | null>(null);

  const form = useForm({
    defaultValues: { fullName: "", country: "", terms: false },
    validators: { onChange: schema },
    onSubmit: async ({ value }) => {
      setSubmitted(JSON.stringify(value));
    },
  });

  const formRef = useFocusInvalidOnSubmit(form);

  return (
    <form
      ref={formRef}
      onSubmit={(event) => {
        event.preventDefault();
        form.handleSubmit();
      }}
    >
      <div className={stack({ gap: "md", direction: "column" })}>
        <FormInput form={form} name="fullName" label="Full name" required />
        <FormSelect
          form={form}
          name="country"
          label="Country"
          items={countries}
          placeholder="Select a country"
          required
        />
        <FormCheckbox
          form={form}
          name="terms"
          label="Agreement"
          errorMode="submitted"
        >
          I accept the terms of service
        </FormCheckbox>
        <FormSubmit form={form}>Continue</FormSubmit>
        {submitted && <p>Submitted: {submitted}</p>}
      </div>
    </form>
  );
}

<script lang="ts">
  import { z } from "zod";
  import {
    createForm,
    FormInput,
    FormSelect,
    FormCheckbox,
    FormSubmit,
    focusInvalidOnSubmit,
  } from "../index.js";
  import { stack } from "@pindoba/styled-system/patterns";

  const countries = [
    { id: "br", label: "Brazil" },
    { id: "us", label: "United States" },
    { id: "pt", label: "Portugal" },
  ];

  const schema = z.object({
    fullName: z.string().min(2, "Use at least 2 characters."),
    country: z.string().min(1, "Pick a country."),
    terms: z.literal(true, { message: "You must accept the terms." }),
  });

  let submitted = $state<string | null>(null);

  const form = createForm(() => ({
    defaultValues: { fullName: "", country: "", terms: false },
    validators: { onChange: schema },
    onSubmit: async ({ value }) => {
      submitted = JSON.stringify(value);
    },
  }));
</script>

<form
  onsubmit={(event) => {
    event.preventDefault();
    form.handleSubmit();
  }}
  {@attach focusInvalidOnSubmit(form)}
>
  <div class={stack({ gap: "md", direction: "column" })}>
    <FormInput {form} name="fullName" label="Full name" required />
    <FormSelect
      {form}
      name="country"
      label="Country"
      items={countries}
      placeholder="Select a country"
      required
    />
    <FormCheckbox {form} name="terms" label="Agreement" errorMode="submitted">
      I accept the terms of service
    </FormCheckbox>
    <FormSubmit {form}>Continue</FormSubmit>
    {#if submitted}<p>Submitted: {submitted}</p>{/if}
  </div>
</form>

Error visibility

By default a field’s errors appear only after it has been touched. Use errorMode to change that:

"touched" (default) — after the user interacts with the field.
"submitted" — only after a submit attempt.
"always" — as soon as the value is invalid.

<!-- Svelte -->
<FormCheckbox {form} name="terms" label="Agreement" errorMode="submitted">
  I accept the terms of service
</FormCheckbox>

<!-- Astro — same prop; the form lives in a client <script> -->
<FormCheckbox name="terms" label="Agreement" errorMode="submitted">
  I accept the terms of service
</FormCheckbox>

Generic FormField

For any control without a convenience wrapper (combobox, date picker, range, your own component), the generic <FormField> renders the field chrome and leaves the control to you.

Svelte hands you both the props bag to spread and the raw TanStack field via a control(props, field) snippet, so you wire value and handlers yourself.
Astro renders the control in the default slot; bindForm auto-wires any standard pindoba control it finds (input, checkbox, Select). Match the control’s id to the field with the exported fieldId(name) helper so the label associates natively.

Toggle the demo’s Code view to see the pattern.

AstroReactSvelteVueTODO

PreviewCode

Username

Your public @handle.

---
import { InputRoot, InputField } from "@pindoba/astro-input";
import Affix from "@pindoba/astro-affix";
import { stack } from "@pindoba/styled-system/patterns";
import FormField from "../FormField.astro";
import { fieldId } from "../field-id";

// The generic <FormField> renders the field chrome (label, description, error
// region, a11y) and leaves the control to you — drop in any pindoba control and
// `bindForm` auto-wires it. Here input parts with a leading "@" Affix prefix
// that <FormInput> doesn't expose. Match the control id to the field id so the
// label associates natively.
---

<pindoba-form id="tsf-generic">
  <div class={stack({ gap: "md", direction: "column" })}>
    <FormField
      name="handle"
      label="Username"
      description="Your public @handle."
    >
      <InputRoot>
        <Affix decorative>@</Affix>
        <InputField id={fieldId("handle")} name="handle" />
      </InputRoot>
    </FormField>
  </div>
</pindoba-form>

<script>
  import "../pindoba-form";
  import type { PindobaFormElement } from "../pindoba-form";
  import { FormApi } from "@tanstack/form-core";
  import { z } from "zod";

  const schema = z.object({
    handle: z
      .string()
      .regex(/^@?[a-z0-9_]{2,}$/i, "Letters, numbers and underscores only."),
  });

  const root = document.querySelector<PindobaFormElement>("#tsf-generic");

  const form = new FormApi({
    defaultValues: { handle: "" },
    validators: { onChange: schema },
    onSubmit: async () => {},
  });
  form.mount();
  if (root) root.form = form;
</script>

import { InputRoot, InputField } from "@pindoba/react-input";
import { Affix } from "@pindoba/react-affix";
import { stack } from "@pindoba/styled-system/patterns";
import { z } from "zod";
import { FormField, useForm, useFocusInvalidOnSubmit } from "../../index";

const schema = z.object({
  handle: z
    .string()
    .regex(/^@?[a-z0-9_]{2,}$/i, "Letters, numbers and underscores only."),
});

export default function GenericFieldDemo() {
  const form = useForm({
    defaultValues: { handle: "" },
    validators: { onChange: schema },
    onSubmit: async () => {},
  });

  const formRef = useFocusInvalidOnSubmit(form);

  // The generic <FormField> hands you the props bag + the raw TanStack field so
  // you can wire ANY control — here input parts with a leading "@" Affix prefix.
  return (
    <form
      ref={formRef}
      onSubmit={(event) => {
        event.preventDefault();
        form.handleSubmit();
      }}
    >
      <div className={stack({ gap: "md", direction: "column" })}>
        <FormField
          form={form}
          name="handle"
          label="Username"
          description="Your public @handle."
          control={({ feedback, ...inputProps }, field) => (
            <InputRoot feedback={feedback}>
              <Affix decorative>@</Affix>
              <InputField
                {...inputProps}
                value={String(field.state.value ?? "")}
                onChange={(event) => field.handleChange(event.target.value)}
                onBlur={() => field.handleBlur()}
              />
            </InputRoot>
          )}
        />
      </div>
    </form>
  );
}

<script lang="ts">
  import { z } from "zod";
  import { createForm, FormField, focusInvalidOnSubmit } from "../index.js";
  import { InputRoot, InputField } from "@pindoba/svelte-input";
  import Affix from "@pindoba/svelte-affix";
  import { stack } from "@pindoba/styled-system/patterns";

  const schema = z.object({
    handle: z
      .string()
      .regex(/^@?[a-z0-9_]{2,}$/i, "Letters, numbers and underscores only."),
  });

  const form = createForm(() => ({
    defaultValues: { handle: "" },
    validators: { onChange: schema },
    onSubmit: async () => {},
  }));
</script>

<!--
  The generic <FormField> hands you the props bag + the raw TanStack field so
  you can wire ANY control — here input parts with a leading "@" Affix prefix.
-->
<form
  onsubmit={(event) => {
    event.preventDefault();
    form.handleSubmit();
  }}
  {@attach focusInvalidOnSubmit(form)}
>
  <div class={stack({ gap: "md", direction: "column" })}>
    <FormField
      {form}
      name="handle"
      label="Username"
      description="Your public @handle."
    >
      {#snippet control(props, field)}
        {@const { feedback, ...inputProps } = props}
        <InputRoot {feedback}>
          <Affix decorative>@</Affix>
          <InputField
            {...inputProps}
            value={field.state.value}
            oninput={(event) => field.handleChange(event.currentTarget.value)}
            onblur={() => field.handleBlur()}
          />
        </InputRoot>
      {/snippet}
    </FormField>
  </div>
</form>

Submit button

<FormSubmit> subscribes to the form’s submit-readiness and renders a Pindoba <Button> that disables while a submission is in flight, setting aria-busy during submit. By default it stays clickable when the form is invalid (so submitting surfaces the errors); set disableWhenInvalid to also disable it while invalid.

<!-- Svelte -->
<FormSubmit {form} emphasis="primary">Save changes</FormSubmit>

<!-- Astro — no form prop; it's bound by the surrounding <pindoba-form> -->
<FormSubmit emphasis="primary" disableWhenInvalid>Save changes</FormSubmit>

#Quick start

#Control wrappers

#Error visibility

#Generic FormField

#Submit button

#API

#Creating the form

#Props

Quick start

Control wrappers

Error visibility

Generic FormField

Submit button

API

Creating the form

Props