Zod

kvant accepts any object with parse and encode methods, including Zod schemas. Pass them directly to kvant wherever a schema is expected.

Installation

npm install zod

The golden rule: never throw

Zod's .parse() throws on invalid input. That is the opposite of the kvant schema contract, where stored values are user-editable and invalid input must degrade gracefully.

When passing a Zod schema to kvant, make it total: either cover every possible input, or attach a fallback with .catch().

import * as z from 'zod'
import { useSearchParams } from 'kvantjs/react'

// ❌ Throws on ?price=abc
const [unsafePrice] = useSearchParams('price', z.coerce.number())

// ✅ Falls back to 0
const [priceWithDefault] = useSearchParams('price', z.coerce.number().catch(0))

// ✅ Falls back to undefined (kvantjs/schema's default behavior)
const [price] = useSearchParams('price', z.coerce.number().optional().catch(undefined))

Codecs

Zod codecs are bidirectional by design, which maps naturally onto kvant's parse/encode contract without any intermediate layers:

import * as z from 'zod'
import { useLocalStorage } from 'kvantjs/react'

// Stored as an ISO string, used as a Date
const dateCodec = z.codec(
  z.iso.datetime().optional().catch(undefined),
  z.date().optional(),
  {
    decode: iso => iso != null ? new Date(iso) : undefined,
    encode: date => date?.toISOString(),
  }
)

const [lastVisit, setLastVisit] = useLocalStorage('last-visit', dateCodec)

See Zod docs for more useful codecs (base64ToBytes, stringToURL, etc.). All of them work with kvant as long as they can't throw on the inputs the desired interface can actually contain.

Mixing kvantjs/schema and Zod

The most practical setup: let kvantjs/schema handle the storage layer (smart casting, defaults, clear-on-default) and pipe into Zod.

import * as kv from 'kvantjs/schema'
import * as z from 'zod'

const uriToEmail = kv.uriComponent().pipe(
  z.email().optional().catch(undefined)
)

.pipe(schema) and all other built-in kvantjs/schema wrappers and combinators accept any { parse, encode } object, not only kvant schemas. The kvant side deals with the raw storage representation, and Zod validates the typed result. Encoding runs in reverse through the same chain. Be careful with this power!

Learn more

• Zod documentation
• Zod codecs
• kvantjs/schema — the built-in alternative
• Custom schema — adapting other libraries