npm install use-standard-schema

useStandardSchema

A React hook for managing form state using any Standard Schema-compliant validator.

![License](https://github.com/garystorey/use-standard-schema/blob/master/LICENSE.md)
!NPM Version

---

- Overview
- Installation
- Usage
- Examples
- API
- Feedback & Support
- Changelog
- License

---

Overview

useStandardSchema wraps a Standard Schema-compliant form definition (e.g. Zod, Valibot, ArkType, etc.) into a React hook for form handling. It streamlines validation, state, error handling, and submission with type safety via the Standard Schema interface.

$3

- Works with any validator that implements the Standard Schema spec
- Provides consistent form APIs regardless of validation library
- Built with TypeScript support, ensuring type-safe validation and form usage
- Integrates easily into React workflows
- Supports nested objects with dot notation (e.g. "address.street1")

$3

- React v18+
- TypeScript (optional, but recommended)
- A validator that implements the Standard Schema v1 interface

---

Installation

bash

npm install use-standard-schema

or

yarn add use-standard-schema

or

pnpm add use-standard-schema





---



Usage



Define your form once with

defineForm, then consume it inside a component with useStandardSchema

tsx

import { defineForm, useStandardSchema, type TypeFromDefinition } from "use-standard-schema"

import * as z from "zod"



const subscriptionForm = defineForm({

  email: {

    label: "Email",

    validate: z.email("Enter a valid email address"),

    defaultValue: "",  // optional

    description: "We'll send occasional updates.", // optional

  },

})



function onSubmitHandler (values: TypeFromDefinition) {

    console.log("Submitted:", values)

}



export function SubscriptionPage() {



  const { getForm, getField } = useStandardSchema(subscriptionForm)

  const formHandlers = getForm(onSubmitHandler)

  const email = getField("email")



  return (

    

        

      {email.label}

              id={email.name}

        name={email.name}

        defaultValue={email.defaultValue}

        // value={defaultValue}

        aria-describedby={email.describedById}

        aria-errormessage={email.errorId}

      />

      {email.description}

      {email.error}



      

    

  )

}

getForm(onSubmit): Returns event handlers for the

. onSubmit

 only runs when valid.

-

getField(name)

: Returns the given field's metadata.



Examples



Additional examples are available.



- CodeSandbox Demo - Try the hook in a live React playground.

- Dependent Fields example - An example that keeps two related fields in sync using

setField and setError

.

- Custom Component example - Share reusable inputs via

FieldData

.

- Valibot example - Build a simple login form powered by Valibot validators.

- Shadcn Field example - Wire

useStandardSchema metadata into the shadcn/ui Field

 primitives.



$3



Nested objects are supported.

tsx

import { defineForm } from "use-standard-schema"

import * as z from "zod"



const addressForm = defineForm({

  address: {

    street1: { label: "Street", validate: z.string().min(2) },

  },

})

$3

useStandardSchema returns the getErrors

 method that returns all of the current validations errors. This can be useful for giving all form error messages in one location. NOTE: This is in addition to the

getField

 method which returns the errors for a given field.

tsx

import type { ErrorEntry } from "use-standard-schema"



const { getErrors } = useStandardSchema(loginForm)

const errors = getErrors()



{errors.length > 0 && (

  

    {errors.map(({ name, label, error }: ErrorEntry) => (

      {label}: {error}

    ))}

  

)}





$3



Use the

isTouched and isDirty

 helper methods to check whether or not the form, or a given field, has been modified or focused by the user.

tsx

  const { isTouched, isDirty } = useStandardSchema(addressForm)



  const isStreetTouched = isTouched("address.street1")

  const isStreetDirty = isDirty("address.street1")



  const isFormTouched = isTouched()

  const isFormDirty = isDirty()





$3



A

FormDefinition

's key is an intersection between a valid JSON key and an HTML name attribute.

ts



const formDefinition = defineForm({

    prefix: z.string(),                // valid

    "first-name": z.string(),          // valid

    "middle_name": z.string(),         // valid

    "last:name": z.string(),           // valid

    "street address": z.string()       // invalid

})

API

useStandardSchema

 returns a helpers for wiring form elements, reading state, and issuing manual updates.



$3



Passing a form definition using

defineForm

 and pass the definition to the hook. The return value exposes the rest of the helpers documented below.

ts

const { getForm, getField, getErrors, setField, setError, resetForm, isTouched, isDirty, watchValues } =

  useStandardSchema(myFormDefinition)





$3



Returns the event handlers for the

. It validates all fields and only invokes your handler when everything passes.

tsx

const form = getForm((values) => console.log(values))



return ...





$3



Returns metadata for a specific field for wiring inputs, labels, and helper text.

tsx

const email = getField("email")



  name={email.name}

  defaultValue={email.defaultValue}

  aria-describedby={email.describedById}

  aria-errormessage={email.errorId}

  aria-invalid={!!email.error}

/>

Enter your email address

{email.error}





$3



Returns structured error data of type

ErrorEntry

 for the whole form or for one specific field - perfect for summary banners or toast notifications.

ts

const allErrors = getErrors()

const emailErrors = getErrors("email")





$3



Clears errors, touched/dirty flags, and restores the original defaults. Note: The hook calls this automatically after a successful submit.

html

npm install use-standard-schema

useStandardSchema

A React hook for managing form state using any Standard Schema-compliant validator.

![License](https://github.com/garystorey/use-standard-schema/blob/master/LICENSE.md)
!NPM Version

---

- Overview
- Installation
- Usage
- Examples
- API
- Feedback & Support
- Changelog
- License

---

Overview

$3

- React v18+
- TypeScript (optional, but recommended)
- A validator that implements the Standard Schema v1 interface

---

Installation

bash

npm install use-standard-schema

or

yarn add use-standard-schema

or

pnpm add use-standard-schema





---



Usage



Define your form once with

defineForm, then consume it inside a component with useStandardSchema

tsx

import { defineForm, useStandardSchema, type TypeFromDefinition } from "use-standard-schema"

import * as z from "zod"



const subscriptionForm = defineForm({

  email: {

    label: "Email",

    validate: z.email("Enter a valid email address"),

    defaultValue: "",  // optional

    description: "We'll send occasional updates.", // optional

  },

})



function onSubmitHandler (values: TypeFromDefinition) {

    console.log("Submitted:", values)

}



export function SubscriptionPage() {



  const { getForm, getField } = useStandardSchema(subscriptionForm)

  const formHandlers = getForm(onSubmitHandler)

  const email = getField("email")



  return (

    

        

      {email.label}

              id={email.name}

        name={email.name}

        defaultValue={email.defaultValue}

        // value={defaultValue}

        aria-describedby={email.describedById}

        aria-errormessage={email.errorId}

      />

      {email.description}

      {email.error}



      

    

  )

}

getForm(onSubmit): Returns event handlers for the

. onSubmit

 only runs when valid.

-

getField(name)

: Returns the given field's metadata.



Examples



Additional examples are available.



- CodeSandbox Demo - Try the hook in a live React playground.

- Dependent Fields example - An example that keeps two related fields in sync using

setField and setError

.

- Custom Component example - Share reusable inputs via

FieldData

.

- Valibot example - Build a simple login form powered by Valibot validators.

- Shadcn Field example - Wire

useStandardSchema metadata into the shadcn/ui Field

 primitives.



$3



Nested objects are supported.

tsx

import { defineForm } from "use-standard-schema"

import * as z from "zod"



const addressForm = defineForm({

  address: {

    street1: { label: "Street", validate: z.string().min(2) },

  },

})

$3

useStandardSchema returns the getErrors

 method that returns all of the current validations errors. This can be useful for giving all form error messages in one location. NOTE: This is in addition to the

getField

 method which returns the errors for a given field.

tsx

import type { ErrorEntry } from "use-standard-schema"



const { getErrors } = useStandardSchema(loginForm)

const errors = getErrors()



{errors.length > 0 && (

  

    {errors.map(({ name, label, error }: ErrorEntry) => (

      {label}: {error}

    ))}

  

)}





$3



Use the

isTouched and isDirty

 helper methods to check whether or not the form, or a given field, has been modified or focused by the user.

tsx

  const { isTouched, isDirty } = useStandardSchema(addressForm)



  const isStreetTouched = isTouched("address.street1")

  const isStreetDirty = isDirty("address.street1")



  const isFormTouched = isTouched()

  const isFormDirty = isDirty()





$3



A

FormDefinition

's key is an intersection between a valid JSON key and an HTML name attribute.

ts



const formDefinition = defineForm({

    prefix: z.string(),                // valid

    "first-name": z.string(),          // valid

    "middle_name": z.string(),         // valid

    "last:name": z.string(),           // valid

    "street address": z.string()       // invalid

})

API

useStandardSchema

 returns a helpers for wiring form elements, reading state, and issuing manual updates.



$3



Passing a form definition using

defineForm

 and pass the definition to the hook. The return value exposes the rest of the helpers documented below.

ts

const { getForm, getField, getErrors, setField, setError, resetForm, isTouched, isDirty, watchValues } =

  useStandardSchema(myFormDefinition)





$3



Returns the event handlers for the

. It validates all fields and only invokes your handler when everything passes.

tsx

const form = getForm((values) => console.log(values))



return ...





$3



Returns metadata for a specific field for wiring inputs, labels, and helper text.

tsx

const email = getField("email")



  name={email.name}

  defaultValue={email.defaultValue}

  aria-describedby={email.describedById}

  aria-errormessage={email.errorId}

  aria-invalid={!!email.error}

/>

Enter your email address

{email.error}





$3



Returns structured error data of type

ErrorEntry

 for the whole form or for one specific field - perfect for summary banners or toast notifications.

ts

const allErrors = getErrors()

const emailErrors = getErrors("email")





$3



Clears errors, touched/dirty flags, and restores the original defaults. Note: The hook calls this automatically after a successful submit.

html

use-standard-schema

useStandardSchema

Table of contents

Overview

$3

$3

Installation

or

or

Usage

Examples

$3

$3

$3

$3

API

$3

$3

$3

$3

$3

$3

$3

$3

$3

$3

Feedback & Support

Changelog

License

use-standard-schema

useStandardSchema

Table of contents

Overview

$3

$3

Installation

or

or

Usage

Examples

$3

$3

$3

$3

API

$3

$3

$3

$3

$3

$3

$3

$3

$3

$3

Feedback & Support

Changelog

License