form-library-integration

This skill builds on state-in-url/feature-state-hook. Read it first for the module-scoped default-state rule.

state-in-url — Form library integration (react-hook-form)

The canonical pattern: one module-scoped defaults object owns the form shape, both useUrlState and useForm consume it, RHF's subscribe() callback pushes form changes into setUrl. Hydration from URL happens through defaultValues: urlState.

Setup

// features/filters/filtersState.ts
import { z } from 'zod';

export const filtersSchema = z.object({
  q: z.string(),
  sort: z.enum(['name', 'date']),
  tags: z.array(z.string()),
});
export type FiltersState = z.infer<typeof filtersSchema>;

export const FILTERS_STATE: FiltersState = {
  q: '',
  sort: 'name',
  tags: [],
};

// features/filters/FiltersForm.tsx
'use client';
import React from 'react';
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { useUrlState } from 'state-in-url/next';
import { FILTERS_STATE, filtersSchema, type FiltersState } from './filtersState';

// `searchParams` forwarded by the server page that renders this form
export function FiltersForm({ searchParams }: { searchParams?: object }) {
  const { urlState, setUrl } = useUrlState(FILTERS_STATE, { searchParams });

  const form = useForm<FiltersState>({
    resolver: zodResolver(filtersSchema),
    defaultValues: urlState, // hydrate from URL on mount
  });

  React.useEffect(() => {
    const sub = form.subscribe({
      formState: { values: true },
      callback: ({ values }) => setUrl(values),
    });
    return () => sub();
  }, [form, setUrl]);

  return (
    <form>
      <input {...form.register('q')} />
      <select {...form.register('sort')}>
        <option value="name">Name</option>
        <option value="date">Date</option>
      </select>
    </form>
  );
}

Core Patterns

Hydrate useForm from urlState

defaultValues: urlState runs once on mount; the form is initialized with whatever the URL contained (or FILTERS_STATE defaults if URL is empty).