<div className="flex justify-end space-x-2">
        <Button variant="outline">Save Draft</Button>
        <Button>Publish</Button>
      </div>
    </div>
  </SideDialogContent>
</SideDialog>
```

### Help and information [#help-and-information]

```tsx
// Help panel - bottom left
<SideDialog position="bottom-left">
  <SideDialogTrigger asChild>
    <Button variant="outline" size="icon">
      <HelpCircle className="size-4" />
    </Button>
  </SideDialogTrigger>
  <SideDialogContent>
    <SideDialogHeader>
      <SideDialogTitle>Need Help?</SideDialogTitle>
      <SideDialogDescription>
        Find answers to common questions or contact support.
      </SideDialogDescription>
    </SideDialogHeader>
    <div className="space-y-3">
      <Button variant="outline" className="w-full">
        <Book className="mr-2 size-4" />
        Documentation
      </Button>
      <Button variant="outline" className="w-full">
        <MessageCircle className="mr-2 size-4" />
        Contact Support
      </Button>
    </div>
  </SideDialogContent>
</SideDialog>
```

## State management [#state-management]

The component supports both controlled and uncontrolled modes, automatically detecting which mode to use based on the props provided:

```tsx
// Uncontrolled: Component manages its own state
<SideDialog position="top-right">
  <SideDialogTrigger asChild>
    <Button>Open</Button>
  </SideDialogTrigger>
  <SideDialogContent>
    <SideDialogHeader>
      <SideDialogTitle>Self-managed State</SideDialogTitle>
    </SideDialogHeader>
  </SideDialogContent>
</SideDialog>

// Controlled: You manage the state
const [open, setOpen] = useState(false);
<SideDialog open={open} onOpenChange={setOpen} position="top-right">
  <SideDialogTrigger asChild>
    <Button>Open</Button>
  </SideDialogTrigger>
  <SideDialogContent>
    <SideDialogHeader>
      <SideDialogTitle>Controlled State</SideDialogTitle>
    </SideDialogHeader>
  </SideDialogContent>
</SideDialog>
```

## Advanced customization [#advanced-customization]

### Custom close behavior [#custom-close-behavior]

```tsx
// Disable the default close button
<SideDialogContent showCloseButton={false}>
  <SideDialogHeader>
    <SideDialogTitle>Custom Controls</SideDialogTitle>
  </SideDialogHeader>
  <SideDialogFooter>
    <SideDialogClose asChild>
      <Button variant="destructive">Cancel</Button>
    </SideDialogClose>
    <SideDialogClose asChild>
      <Button>Confirm</Button>
    </SideDialogClose>
  </SideDialogFooter>
</SideDialogContent>
```

### Custom styling [#custom-styling]

```tsx
// Custom dialog appearance
<SideDialogContent className="border-primary shadow-xl bg-gradient-to-b from-background to-muted">
  <SideDialogHeader>
    <SideDialogTitle className="text-primary">Custom Style</SideDialogTitle>
  </SideDialogHeader>
</SideDialogContent>
```

## Examples [#examples]

## Props [#props]

<TypeTable
  type="{
  open: {
    description: 'Controlled open state (optional)',
    type: 'boolean?',
  },
  onOpenChange: {
    description: 'Callback when open state changes',
    type: '(open: boolean) => void?',
  },
  position: {
    description: 'Position of the dialog: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "left" | "right" (default: "bottom-right")',
    type: 'SideDialogPosition?',
  },
  size: {
    description: 'Size of the dialog: "xs" | "sm" | "md" | "lg" | "xl" | "2xl" with automatic responsive constraints (default: "sm")',
    type: 'SideDialogSize?',
  },
  children: {
    description: 'Dialog content (SideDialogTrigger and SideDialogContent)',
    type: 'React.ReactNode',
  },
}"
/>

## SideDialogContent Props [#sidedialogcontent-props]

## SideDialogBody Props [#sidedialogbody-props]

## SideDialogTrigger Props [#sidedialogtrigger-props]

# Submit Button (/components/submit-button)

### Built-in features [#built-in-features]

* **Automatic loading state**: Shows spinner icon when `loading` prop is true
* **Full-width by default**: Optimized for form layouts
* **Customizable icon**: Can override the default loading spinner
* **Form integration**: Native `type="submit"` behavior

## Common use cases [#common-use-cases]

### Basic form submission [#basic-form-submission]

```tsx
<SubmitButton children="Save Changes" loading={isSaving} />

<SubmitButton loading={isSaving}>
  <span className="flex items-center">
    <Send className="mr-2 h-4 w-4" />
    Send Message
  </span>
</SubmitButton>
```

### With custom icon [#with-custom-icon]

```tsx
<SubmitButton 
  children="Processing Payment"
  loading={isProcessing}
  icon={<CreditCard className="mr-2 h-4 w-4 animate-pulse" />}
/>
```

### With JSX label [#with-jsx-label]

```tsx
<SubmitButton 
  children={
    <span className="flex items-center">
      <Send className="mr-2 h-4 w-4" />
      Send Message
    </span>
  }
  loading={isSending}
/>
```

### Custom styling [#custom-styling]

```tsx
<SubmitButton 
  children="Delete Account"
  loading={isDeleting}
  className="bg-destructive hover:bg-destructive/90"
  disabled={!confirmed}
/>
```

## Examples [#examples]

## Props [#props]

# Theme Button (/components/theme-button)

## Ready-to-use theme toggle [#ready-to-use-theme-toggle]

The button automatically cycles through these states:

* **System**: Uses the user's OS preference (🖥️ Laptop icon)
* **Light**: Forces light mode (☀️ Sun icon)
* **Dark**: Forces dark mode (🌙 Moon icon)

With `ThemeButton`, a complete theme switcher in one line:

### With ThemeButton - simple and complete [#with-themebutton---simple-and-complete]

```tsx
<ThemeButton />
```

### With text label [#with-text-label]

```tsx
<ThemeButton withText={true} />
```

## Setup with next-themes [#setup-with-next-themes]

First, make sure you have [`next-themes`](https://ui.shadcn.com/docs/dark-mode/next) installed and configured:

## Examples [#examples]

## Props [#props]

# Address Field (/components/react-hook-form/address-field)

`AddressField` is a compound field component that manages a full `AddressData` sub-tree (street, city, postal code, country, full address, place ID) under a single name prefix. It wires Google Places autocomplete to the form so that selecting a suggestion writes every sub-field at once.

The field binds to the form via a typed lens from [`@hookform/lenses`](https://github.com/react-hook-form/lenses). The parent passes `lens={lens.focus('address')}` — a `Lens<AddressData>` — and the component focuses internally on each sub-field. No string paths, no `useFormContext`, no name-prefix hacks.

#### Built-in features [#built-in-features]

* **Compound field**: manages `street`, `city`, `postalCode`, `country`, `fullAddress`, and `placeId` under a single sub-tree
* **Typed lens binding**: `lens.focus('address')` autocompletes from your form's value type — no `<MyForm>` generic at the call site
* **Google Places autocomplete**: server action, popover dropdown, keyboard navigation, debounced search
* **Zod schema export**: `addressSchema` is published alongside the component for easy composition (`z.object({ address: addressSchema })`)

## Configuration [#configuration]

This component requires a Google Places API key. Add `GOOGLE_PLACES_API_KEY` to your `.env` file:

```bash
GOOGLE_PLACES_API_KEY=your_api_key_here
```

To customize the default country, language, or debounce, edit the constants in the component:

```tsx
const DEFAULT_COUNTRY = 'US'; // Country code for suggestions
const LANGUAGE_RESULT = 'en';  // Language code for results
const DEBOUNCE_TIME = 300;     // API call delay in milliseconds
```

## Setup [#setup]

Field components bind via `@hookform/lenses`. Create a lens once per form, then focus on the address sub-tree:

```tsx
import { useLens } from '@hookform/lenses';
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { Form } from '@/components/ui/form';
import { AddressField, addressSchema } from '@/components/ui/shuip/react-hook-form/address-field';

const schema = z.object({ address: addressSchema });

const form = useForm<z.infer<typeof schema>>({
  resolver: zodResolver(schema),
  defaultValues: {
    address: { street: '', city: '', postalCode: '', country: '', fullAddress: '' },
  },
});
const lens = useLens({ control: form.control });

<Form {...form}>
  <form onSubmit={form.handleSubmit(onSubmit)}>
    <AddressField lens={lens.focus('address')} country='FR' />
  </form>
</Form>
```

The `<Form>` wrapper is required — it provides shadcn's `FormProvider` which `FormLabel` and `FormMessage` use internally.

## Compound field [#compound-field]

Unlike a single-input field, `AddressField` writes to every sub-field of the `AddressData` sub-tree when the user picks a place suggestion. Internally, it derives one controller per sub-field from the lens:

```tsx
const fullAddress = useController(lens.focus('fullAddress').interop());
const street      = useController(lens.focus('street').interop());
const city        = useController(lens.focus('city').interop());
const postalCode  = useController(lens.focus('postalCode').interop());
const country     = useController(lens.focus('country').interop());
const placeId     = useController(lens.focus('placeId').interop());
```

When Google Places returns details for a selected suggestion, each `field.onChange(...)` populates its sub-field — no global `setValue` call against string paths.

## Less boilerplate [#less-boilerplate]

Traditional address forms require multiple fields and manual validation:

```tsx
<Input name='address.street' placeholder='Street' />
<Input name='address.city' placeholder='City' />
<Input name='address.postalCode' placeholder='Postal Code' />
<Input name='address.country' placeholder='Country' />
// ...manual validation and state management
```

With `AddressField`, this reduces to a single component with automatic validation and place lookup:

```tsx
<AddressField lens={lens.focus('address')} placeholder='Enter your address' />
```

## Schema composition [#schema-composition]

`addressSchema` is exported alongside the component so consumers can compose it into a larger form schema:

```tsx
import { addressSchema } from '@/components/ui/shuip/react-hook-form/address-field';

const schema = z.object({
  customer: z.string().min(1),
  shipping: addressSchema,
  billing: addressSchema,
});
```

The component returns structured address data on submit:

```tsx
{
  address: {
    street: '123 Main St',
    city: 'Paris',
    postalCode: '75001',
    country: 'France',
    fullAddress: '123 Main St, 75001 Paris, France',
    placeId: 'abcdef123456',
  }
}
```

## Examples [#examples]

## Props [#props]

<TypeTable
  type="{
  lens: {
    description: 'Typed lens from useLens — points at an AddressData sub-tree.',
    type: 'Lens<AddressData>',
  },
  label: {
    description: 'Field label text (default: "Address")',
    type: 'string?',
  },
  placeholder: {
    description: 'Placeholder text for the input (default: "Enter your address")',
    type: 'string?',
  },
  description: {
    description: 'Helper text displayed below the field',
    type: 'string?',
  },
  country: {
    description: 'Country code for address suggestions (default: "US")',
    type: 'string?',
  },
  props: {
    description: "Native HTML input props (disabled, className, etc.) — spread on Input, except value/onChange which are managed.",
    type: "Omit<React.ComponentProps<typeof Input>, 'value' | 'onChange'>",
  },
}"
/>

# Autocomplete Field (/components/react-hook-form/autocomplete-field)

`AutocompleteField` is a text input that proposes matching strings as the user types, while still allowing any free-text value. It binds to React Hook Form through `@hookform/lenses` (`lens` prop) and stores a plain `string`.

Use it when a field has a set of common values worth suggesting (sources, tags, cities…) but you don't want to force the user to pick from the list.

#### Built-in features [#built-in-features]

* **Two suggestion modes**: a static `suggestions` array (filtered client-side) or an async `onSearch` function (debounced fetch).
* **Free text**: the typed value is always kept — closing the dropdown without selecting commits what was typed.
* **Keyboard navigation**: ArrowUp/ArrowDown to move, Enter to select, Escape to close.
* **Custom matching**: override the default case-insensitive substring match via `filter` (static mode).

## Examples [#examples]

## Props [#props]

<TypeTable
  type="{
  lens: {
    description: 'React Hook Form lens focused on a string field (@hookform/lenses)',
    type: 'Lens<string>',
  },
  label: {
    description: 'Field label text',
    type: 'string?',
  },
  description: {
    description: 'Helper text displayed below the input',
    type: 'string?',
  },
  placeholder: {
    description: 'Input placeholder',
    type: 'string?',
  },
  suggestions: {
    description: 'Static list of suggestions, filtered client-side. Ignored when onSearch is provided.',
    type: 'string[]?',
  },
  onSearch: {
    description: 'Async resolver called with the current query; its result is shown as-is. Takes precedence over suggestions.',
    type: '((query: string) => Promise<string[]>)?',
  },
  emptyText: {
    description: 'Message shown when there are no matches',
    type: 'string?',
    default: "'No results'",
  },
  debounceMs: {
    description: 'Debounce delay before calling onSearch (async mode only)',
    type: 'number?',
    default: '300',
  },
  filter: {
    description: 'Custom matcher for static mode; defaults to case-insensitive substring',
    type: '((suggestion: string, query: string) => boolean)?',
  },
}"
/>

# Checkbox Field (/components/react-hook-form/checkbox-field)

`CheckboxField` is a boolean input component that encapsulates React Hook Form's field management with shadcn/ui's design system. It combines Radix UI's Checkbox with an inline clickable label, making the entire label area interactive — not just the checkbox itself.

The field binds to the form via a typed lens from [`@hookform/lenses`](https://github.com/react-hook-form/lenses) — no call-site generic, just `lens.focus('fieldName')` with full autocomplete from your form's value type.

#### Built-in features [#built-in-features]

* **Typed lens binding**: `lens.focus('agree')` autocompletes from your form's value type — no `<MyForm>` generic at the call site
* **Clickable inline label**: positioned next to the checkbox for a larger hit target
* **Boolean field type**: bound via `checked` / `onCheckedChange` — no manual event wiring
* **Required validation**: pair with Zod's `.refine()` for terms acceptance flows
* **Zod validation**: native integration with react-hook-form and Zod via resolver

## Setup [#setup]

Field components bind via `@hookform/lenses`. Create a lens once per form:

```tsx
import { useLens } from '@hookform/lenses';
import { useForm } from 'react-hook-form';
import { Form } from '@/components/ui/form';
import { CheckboxField } from '@/components/ui/shuip/react-hook-form/checkbox-field';

const form = useForm<MyForm>({ defaultValues: { agree: false } });
const lens = useLens({ control: form.control });

<Form {...form}>
  <form onSubmit={form.handleSubmit(onSubmit)}>
    <CheckboxField lens={lens.focus('agree')} label='I agree' />
  </form>
</Form>
```

The `<Form>` wrapper is required — it provides shadcn's `FormProvider` which `FormLabel` and `FormMessage` use internally.

## Less boilerplate [#less-boilerplate]

React Hook Form's standard approach uses render props to access field state:

```tsx
<FormField
  control={form.control}
  name="agree"
  render={({ field }) => (
    <FormItem>
      <FormControl>
        <Checkbox checked={field.value} onCheckedChange={field.onChange} />
      </FormControl>
      <FormLabel>I accept the terms and conditions</FormLabel>
      <FormMessage />
    </FormItem>
  )}
/>
```

With `CheckboxField`, this reduces to a single declarative component:

```tsx
<CheckboxField
  lens={lens.focus('agree')}
  label='I accept the terms and conditions'
  description='Read our terms before proceeding'
/>
```

## Examples [#examples]

## Required checkbox [#required-checkbox]

For terms acceptance, validate that the value is `true` with Zod's `.refine()`:

```tsx
const schema = z.object({
  terms: z.boolean().refine((val) => val === true, {
    message: 'You must accept the terms and conditions',
  }),
});

const form = useForm<z.infer<typeof schema>>({
  defaultValues: { terms: false },
  resolver: zodResolver(schema),
});
const lens = useLens({ control: form.control });

<CheckboxField
  lens={lens.focus('terms')}
  label='I accept the terms and conditions'
  description='Read our terms before proceeding'
/>
```

## Props [#props]

<TypeTable
  type="{
  lens: {
    description: 'Typed lens from useLens (see Setup section).',
    type: 'Lens<boolean>',
  },
  label: {
    description: 'Clickable label displayed next to the checkbox',
    type: 'string',
  },
  description: {
    description: 'Helper text displayed below the checkbox',
    type: 'string?',
  },
  props: {
    description: 'Native Checkbox props — spread on Checkbox, except checked/onCheckedChange which are managed.',
    type: "Omit<React.ComponentProps<typeof Checkbox>, 'checked' | 'onCheckedChange'>",
  },
}"
/>

# Date Field (/components/react-hook-form/date-field)

`DateField` is a single-date picker that encapsulates React Hook Form's field management with the shadcn `Calendar` primitive. The trigger is an outline `Button` (full-width) that shows the selected date formatted via [`date-fns`](https://date-fns.org); clicking it opens a `Popover` containing the calendar.

The field binds to the form via a typed lens from [`@hookform/lenses`](https://github.com/react-hook-form/lenses). The value type is `Date | undefined` — `undefined` represents an empty selection (matching `react-day-picker`'s convention).

#### Built-in features [#built-in-features]

* **Typed lens binding**: `lens.focus('dueDate')` — `Lens<Date | undefined>` is enforced at compile time
* **Locale-aware formatting**: defaults to `en-US`; pass any `date-fns/locale` via the `locale` prop
* **Bounded selection**: `minDate` / `maxDate` disable days outside the range in the calendar UI
* **Accessible trigger**: a real `<Button>` with `aria-invalid` reflecting `fieldState.invalid`
* **Zod validation**: integrates with `z.date().min(...).max(...)` via the standard resolver

## Setup [#setup]

```tsx
import { useLens } from '@hookform/lenses';
import { useForm } from 'react-hook-form';
import { Form } from '@/components/ui/form';
import { DateField } from '@/components/ui/shuip/react-hook-form/date-field';

const form = useForm<{ dueDate: Date | undefined }>({
  defaultValues: { dueDate: undefined },
});
const lens = useLens({ control: form.control });

<Form {...form}>
  <form onSubmit={form.handleSubmit(onSubmit)}>
    <DateField lens={lens.focus('dueDate')} label='Due date' />
  </form>
</Form>
```

The `<Form>` wrapper is required — it provides React Hook Form's `FormProvider` context.

## Bounded selection [#bounded-selection]

Use `minDate` and `maxDate` to disable out-of-range days directly in the calendar:

```tsx
<DateField
  lens={lens.focus('appointment')}
  label='Appointment'
  minDate={new Date()}
  maxDate={oneYearFromNow}
/>
```

Disabled days remain visible but cannot be selected. Validate the same bounds in your schema so submission also rejects out-of-range values.

## Examples [#examples]

## Props [#props]

<TypeTable
  type="{
  lens: {
    description: 'Typed lens from useLens, focused on a Date | undefined field.',
    type: 'Lens<Date | undefined>',
  },
  label: {
    description: 'Field label text',
    type: 'string?',
  },
  description: {
    description: 'Helper text displayed below the trigger',
    type: 'string?',
  },
  placeholder: {
    description: 'Text shown on the trigger when no date is selected',
    type: 'string?',
    default: "'Pick a date'",
  },
  minDate: {
    description: 'Earliest selectable date (inclusive). Days before are disabled.',
    type: 'Date?',
  },
  maxDate: {
    description: 'Latest selectable date (inclusive). Days after are disabled.',
    type: 'Date?',
  },
  locale: {
    description: 'date-fns locale used for formatting and weekday labels',
    type: 'Locale?',
    default: 'enUS',
  },
  dateFormat: {
    description: 'date-fns format string for the trigger label',
    type: 'string?',
    default: "'PPP'",
  },
  disabled: {
    description: 'Disables the trigger button',
    type: 'boolean?',
  },
  triggerProps: {
    description: 'Additional props forwarded to the trigger Button',
    type: 'React.ComponentProps<typeof Button>?',
  },
}"
/>

# Date Range Field (/components/react-hook-form/date-range-field)

`DateRangeField` is a from–to date picker bound to React Hook Form. It wraps the shadcn `Calendar` primitive in `mode='range'` inside a `Popover`, and binds via a typed lens from [`@hookform/lenses`](https://github.com/react-hook-form/lenses) — no string paths, no `<MyForm>` generic at the call site.

The bound value is a `DateRange` from `react-day-picker`:

```ts
type DateRange = { from?: Date; to?: Date } | undefined;
```

#### Built-in features [#built-in-features]

* **Typed lens binding**: `lens.focus('range')` autocompletes from your form's value type
* **Two-month side-by-side display**: canonical UX for picking a range that crosses months
* **Bounded selection**: `minDate` / `maxDate` translate to the Calendar `disabled` matcher
* **Locale aware**: optional `date-fns` `Locale` passed through to both label formatting and the underlying Calendar

## Setup [#setup]

The field binds via `@hookform/lenses`. Declare the value as an optional `DateRange` in your schema, then focus the lens on the range field:

```tsx
import type { DateRange } from 'react-day-picker';
import { useLens } from '@hookform/lenses';
import { useForm } from 'react-hook-form';
import { Form } from '@/components/ui/form';
import { DateRangeField } from '@/components/ui/shuip/react-hook-form/date-range-field';

type Values = { stay: DateRange | undefined };

const form = useForm<Values>({ defaultValues: { stay: undefined } });
const lens = useLens({ control: form.control });

<Form {...form}>
  <form onSubmit={form.handleSubmit(onSubmit)}>
    <DateRangeField lens={lens.focus('stay')} label='Stay' />
  </form>
</Form>
```

The `<Form>` wrapper is required — it provides React Hook Form's `FormProvider` context.

## Trigger label [#trigger-label]

The trigger button renders a label derived from the current value:

* both ends set → `"<from> – <to>"` using `date-fns` `format(date, 'PPP', { locale })`
* only `from` set → just the `from` date
* neither set → the `placeholder` prop

## Validation [#validation]

For a required range, pair the field with a Zod schema that enforces both ends and the ordering. See the `validation` example below.

```tsx
const schema = z.object({
  range: z
    .object({
      from: z.date({ message: 'Start date is required' }),
      to: z.date({ message: 'End date is required' }),
    })
    .refine((value) => value.to >= value.from, {
      message: 'End date must be on or after the start date',
      path: ['to'],
    }),
});
```

## Examples [#examples]

## Props [#props]

<TypeTable
  type="{
  lens: {
    description: 'Typed lens from useLens — points at a DateRange | undefined value.',
    type: 'Lens<DateRange | undefined>',
  },
  label: {
    description: 'Field label text',
    type: 'string?',
  },
  description: {
    description: 'Helper text displayed below the trigger',
    type: 'string?',
  },
  placeholder: {
    description: 'Trigger label when no date is selected (default: "Pick a date range")',
    type: 'string?',
  },
  minDate: {
    description: 'Earliest selectable date — passed to Calendar as disabled.before',
    type: 'Date?',
  },
  maxDate: {
    description: 'Latest selectable date — passed to Calendar as disabled.after',
    type: 'Date?',
  },
  locale: {
    description: 'date-fns Locale used for label formatting and the Calendar',
    type: 'Locale?',
  },
  disabled: {
    description: 'Disable the trigger button',
    type: 'boolean?',
  },
}"
/>

# Datetime Field (/components/react-hook-form/datetime-field)

`DatetimeField` is a single-value date + time picker that stores its selection as one `Date` carrying both the day and the hours/minutes. It wraps shadcn's `Calendar` and a native `<input type="time">` inside a `Popover`, and binds to the form via a typed lens from [`@hookform/lenses`](https://github.com/react-hook-form/lenses).

For date-only fields, use `Calendar` directly. This component is for cases where the time of day matters as much as the date — meeting start, deadline, deliverable, etc.

#### Built-in features [#built-in-features]

* **Single `Date` value**: day + hours + minutes live in one field — no separate date/time pieces to reconcile
* **Typed lens binding**: `lens.focus('scheduledAt')` autocompletes from your form's value type
* **Locale-aware label**: trigger renders via `date-fns` `format(value, 'PPp', { locale })`
* **Bounds**: `minDate` / `maxDate` disable out-of-range days on the calendar
* **Time step**: native `<input type="time" step="...">` for minute or second granularity

## Setup [#setup]

```tsx
import { useLens } from '@hookform/lenses';
import { useForm } from 'react-hook-form';
import { z } from 'zod';
import { Form } from '@/components/ui/form';
import { DatetimeField } from '@/components/ui/shuip/react-hook-form/datetime-field';

const schema = z.object({ scheduledAt: z.date() });
type Values = z.infer<typeof schema>;

const form = useForm<Values>({ defaultValues: { scheduledAt: undefined } });
const lens = useLens({ control: form.control });

<Form {...form}>
  <form onSubmit={form.handleSubmit(onSubmit)}>
    <DatetimeField lens={lens.focus('scheduledAt')} label='Scheduled at' />
  </form>
</Form>
```

The `<Form>` wrapper is required — it provides React Hook Form's `FormProvider` context.

## Behavior [#behavior]

* **First date pick:** when the field is empty and the user picks a day, hours and minutes default to `00:00`. When the field already has a value, the existing hours/minutes are preserved.
* **Time change:** only the hours/minutes are updated; the date portion is preserved.
* **Trigger label:** `format(value, 'PPp', { locale })` — e.g. `May 22, 2026, 2:30 PM`. When empty, falls back to `placeholder`.

## Examples [#examples]

## Props [#props]

<TypeTable
  type="{
  lens: {
    description: 'Typed lens from useLens (see Setup section).',
    type: 'Lens<Date | undefined>',
  },
  label: {
    description: 'Field label text',
    type: 'string?',
  },
  description: {
    description: 'Helper text displayed below the trigger',
    type: 'string?',
  },
  placeholder: {
    description: 'Trigger label shown when no date is selected',
    type: 'string?',
    default: "'Pick a date & time'",
  },
  minDate: {
    description: 'Earliest selectable date (inclusive). Disables earlier days on the calendar.',
    type: 'Date?',
  },
  maxDate: {
    description: 'Latest selectable date (inclusive). Disables later days on the calendar.',
    type: 'Date?',
  },
  locale: {
    description: 'date-fns locale used for the trigger label and the calendar.',
    type: 'Locale?',
  },
  disabled: {
    description: 'Disables the trigger button.',
    type: 'boolean?',
  },
  step: {
    description: 'Time input step in seconds. 60 = 1 minute, 1 = 1 second.',
    type: 'number?',
    default: '60',
  },
}"
/>

# Inline Edit Field (/components/react-hook-form/inline-edit)

A click-to-edit field for React Hook Form. The value displays as text and turns into an
editable input on click; read and edit share one typography scale, so editing is seamless.
On each commit the field writes its value to the form and validates it — an invalid value
keeps the field in edit mode with the error shown inline.

Persisting is the form's job, not the field's: subscribe to the form with `form.watch` (or
submit it). The example below autosaves the whole form to `localStorage` from a single
`watch` subscription, so one handler covers every field.

## Examples [#examples]

## Props [#props]

<TypeTable
  type="{
  lens: {
    description: 'The lens focused on this field (from @hookform/lenses).',
    type: 'Lens<string>',
  },
  label: {
    description: 'Field label.',
    type: 'string',
  },
  description: {
    description: 'Hint shown in a popover behind an info icon, next to the value.',
    type: 'string',
  },
  orientation: {
    description: 'Label layout, forwarded to the underlying Field.',
    type: "'vertical' | 'horizontal'",
    default: "'vertical'",
  },
  input: {
    description: 'Built-in editor rendered in edit mode.',
    type: "'text' | 'textarea'",
    default: "'text'",
  },
  variant: {
    description: 'Edit-mode chrome. ghost is seamless; boxed shows a thin bordered input.',
    type: "'ghost' | 'boxed'",
    default: "'ghost'",
  },
  size: {
    description: 'Typography and spacing scale, shared by the read and edit states.',
    type: "'sm' | 'default' | 'title'",
    default: "'default'",
  },
  placeholder: {
    description: 'Shown when the value is empty, in read mode.',
    type: 'string',
  },
  canEdit: {
    description: 'Whether clicking enters edit mode.',
    type: 'boolean',
    default: 'true',
  },
}"
/>

# Input Field (/components/react-hook-form/input-field)

`InputField` is a text input component that encapsulates React Hook Form's field management with shadcn/ui's design system. It handles all the boilerplate of connecting form state to an input element: wiring event handlers, displaying errors, managing touched states, and rendering consistent UI.

For numeric inputs, use [`NumberField`](/components/react-hook-form/number-field) instead.

#### Built-in features [#built-in-features]

* **Typed lens binding**: `lens.focus('name')` autocompletes from your form's value type — no `<MyForm>` generic at the call site
* **Tooltip integration**: optional InfoIcon button with tooltip content via `tooltip` prop
* **InputGroup ready**: built on shadcn InputGroup for seamless addon integration
* **Zod validation**: native integration with react-hook-form and Zod via resolver

## Setup [#setup]

Field components bind via `@hookform/lenses`. Create a lens once per form:

```tsx
import { useLens } from '@hookform/lenses';
import { useForm } from 'react-hook-form';
import { Form } from '@/components/ui/form';
import { InputField } from '@/components/ui/shuip/react-hook-form/input-field';

const form = useForm<MyForm>({ defaultValues: { email: '' } });
const lens = useLens({ control: form.control });

<Form {...form}>
  <form onSubmit={form.handleSubmit(onSubmit)}>
    <InputField lens={lens.focus('email')} label='Email' />
  </form>
</Form>
```

The `<Form>` wrapper is required — it provides React Hook Form's `FormProvider` context.

## Less boilerplate [#less-boilerplate]

React Hook Form's standard approach uses render props to access field state:

```tsx
<Controller
  control={form.control}
  name="email"
  render={({ field, fieldState }) => (
    <Field data-invalid={fieldState.invalid}>
      <FieldLabel htmlFor={field.name}>Email</FieldLabel>
      <Input {...field} id={field.name} aria-invalid={fieldState.invalid} placeholder="your@email.com" />
      <FieldDescription>Your email address</FieldDescription>
      {fieldState.invalid && <FieldError errors={[fieldState.error]} />}
    </Field>
  )}
/>
```

With `InputField`, this reduces to a single declarative component:

```tsx
<InputField
  lens={lens.focus('email')}
  label="Email"
  description="Your email address"
  placeholder="your@email.com"
/>
```

## Examples [#examples]

## Props [#props]

<TypeTable
  type="{
  lens: {
    description: 'Typed lens from useLens (see Setup section).',
    type: 'Lens<string>',
  },
  label: {
    description: 'Field label text',
    type: 'string?',
  },
  description: {
    description: 'Helper text displayed below the input',
    type: 'string?',
  },
  tooltip: {
    description: 'Tooltip content displayed in an info icon button',
    type: 'React.ReactNode?',
  },
  props: {
    description: 'Native HTML input props (placeholder, disabled, etc.) — spread on InputGroupInput, except value/onChange which are managed.',
    type: "Omit<React.ComponentProps<typeof InputGroupInput>, 'value' | 'onChange'>",
  },
}"
/>

# Month Field (/components/react-hook-form/month-field)

`MonthField` is a month picker that wraps the shadcn `Calendar` primitive inside a `Popover`. The user picks any day in a month and the field stores the **first day of that month** as a `Date` — perfect for "billing month", "report period", "subscription start" use cases where the day component is noise.

The field binds to the form via a typed lens from [`@hookform/lenses`](https://github.com/react-hook-form/lenses): `lens.focus('billingMonth')` autocompletes from your form's value type — no `<MyForm>` generic at the call site.

#### Built-in features [#built-in-features]

* **First-day normalization**: any day the user clicks is internally rewritten to `new Date(year, month, 1)`, so the stored value behaves as a month bucket
* **Dropdown caption**: month and year dropdowns in the calendar header (`captionLayout='dropdown'`)
* **Bounded range**: `minDate` / `maxDate` drive both the calendar's disabled days and its dropdown bounds via `startMonth` / `endMonth`
* **Locale aware**: `locale` is forwarded to `date-fns` `format` and to the calendar
* **Typed lens binding**: `lens.focus('month')` autocompletes from your form's value type

## Setup [#setup]

```tsx
import { useLens } from '@hookform/lenses';
import { useForm } from 'react-hook-form';
import { Form } from '@/components/ui/form';
import { MonthField } from '@/components/ui/shuip/react-hook-form/month-field';

type Values = { billingMonth: Date | undefined };

const form = useForm<Values>({ defaultValues: { billingMonth: undefined } });
const lens = useLens({ control: form.control });

<Form {...form}>
  <form onSubmit={form.handleSubmit(onSubmit)}>
    <MonthField lens={lens.focus('billingMonth')} label='Billing month' />
  </form>
</Form>
```

## Value shape [#value-shape]

The stored value is always either `undefined` or a `Date` whose day component is `1`. Consumers can compare months by `value.getTime()` without worrying about time-of-day drift:

```ts
const a = new Date(2026, 4, 1);  // May 2026
const b = new Date(2026, 4, 1);  // May 2026
a.getTime() === b.getTime();     // true
```

To format the stored value elsewhere, use the same `'MMMM yyyy'` pattern from `date-fns`:

```ts
import { format } from 'date-fns';
format(values.billingMonth, 'MMMM yyyy'); // 'May 2026'
```

## Examples [#examples]

## Props [#props]

<TypeTable
  type="{
  lens: {
    description: 'Typed lens from useLens, focused on a Date | undefined field.',
    type: 'Lens<Date | undefined>',
  },
  label: {
    description: 'Field label text',
    type: 'string?',
  },
  description: {
    description: 'Helper text displayed below the trigger',
    type: 'string?',
  },
  placeholder: {
    description: 'Trigger text shown when no month is selected',
    type: 'string?',
    default: "'Pick a month'",
  },
  minDate: {
    description: 'Earliest selectable month. Drives both disabled days and startMonth for the year dropdown.',
    type: 'Date?',
  },
  maxDate: {
    description: 'Latest selectable month. Drives both disabled days and endMonth for the year dropdown.',
    type: 'Date?',
  },
  locale: {
    description: 'date-fns Locale forwarded to format() and to Calendar.',
    type: 'Locale?',
  },
  disabled: {
    description: 'Disables the trigger button.',
    type: 'boolean?',
  },
  className: {
    description: 'Extra classes applied to the trigger button.',
    type: 'string?',
  },
}"
/>

# Number Field (/components/react-hook-form/number-field)

`NumberField` binds a numeric form field (`Lens<number>`) to a `type='number'` or `type='range'` input. The input writes back `e.target.valueAsNumber` so the form state stays correctly typed as `number`. Empty input becomes `NaN`, which validators can check with `Number.isNaN(value)`.

For text fields, use [`InputField`](/components/react-hook-form/input-field) instead.

#### Built-in features [#built-in-features]

* **Typed lens binding**: `lens.focus('quantity')` requires a numeric form field — typing is enforced
* **`valueAsNumber` write-back**: form state stays `number`, not `string`
* **Range slider support**: pass `type='range'` to render a slider
* **Tooltip integration**: optional InfoIcon button with tooltip content via `tooltip` prop
* **InputGroup ready**: built on shadcn InputGroup for seamless addon integration
* **Zod validation**: native integration with react-hook-form and Zod via resolver

## Setup [#setup]

```tsx
import { useLens } from '@hookform/lenses';
import { useForm } from 'react-hook-form';
import { Form } from '@/components/ui/form';
import { NumberField } from '@/components/ui/shuip/react-hook-form/number-field';

const form = useForm<{ quantity: number; ratio: number }>({
  defaultValues: { quantity: 1, ratio: 0.5 },
});
const lens = useLens({ control: form.control });

<Form {...form}>
  <form onSubmit={form.handleSubmit(onSubmit)}>
    <NumberField lens={lens.focus('quantity')} label='Quantity' />
    <NumberField lens={lens.focus('ratio')} type='range' label='Ratio' min={0} max={1} step={0.1} />
  </form>
</Form>
```

## Examples [#examples]

## Props [#props]

<TypeTable
  type="{
  lens: {
    description: 'Typed lens from useLens, focused on a numeric form field.',
    type: 'Lens<number>',
  },
  label: {
    description: 'Field label text',
    type: 'string?',
  },
  description: {
    description: 'Helper text displayed below the input',
    type: 'string?',
  },
  tooltip: {
    description: 'Tooltip content displayed in an info icon button',
    type: 'React.ReactNode?',
  },
  props: {
    description: "Native HTML input props (type, min, max, step, etc.) — spread on InputGroupInput, except value/onChange which are managed. Defaults type to 'number'.",
    type: "Omit<React.ComponentProps<typeof InputGroupInput>, 'value' | 'onChange'>",
  },
}"
/>

# Password Field (/components/react-hook-form/password-field)

`PasswordField` is a password input component that encapsulates React Hook Form's field management with shadcn/ui's design system. It handles all the boilerplate of connecting form state to an input element: wiring event handlers, displaying errors, managing touched states, and rendering consistent UI — with a built-in visibility toggle on top.

#### Built-in features [#built-in-features]

* **Typed lens binding**: `lens.focus('password')` autocompletes from your form's value type — no `<MyForm>` generic at the call site
* **One-click visibility toggle**: Eye/EyeOff icons switch between masked and plain text
* **Tooltip integration**: optional InfoIcon button with tooltip content via `tooltip` prop
* **InputGroup ready**: built on shadcn InputGroup for seamless addon integration
* **Zod validation**: native integration with react-hook-form and Zod via resolver

## Setup [#setup]

Field components bind via `@hookform/lenses`. Create a lens once per form:

```tsx
import { useLens } from '@hookform/lenses';
import { useForm } from 'react-hook-form';
import { Form } from '@/components/ui/form';
import { PasswordField } from '@/components/ui/shuip/react-hook-form/password-field';

const form = useForm<MyForm>({ defaultValues: { password: '' } });
const lens = useLens({ control: form.control });

<Form {...form}>
  <form onSubmit={form.handleSubmit(onSubmit)}>
    <PasswordField lens={lens.focus('password')} label='Password' />
  </form>
</Form>
```

The `<Form>` wrapper is required — it provides shadcn's `FormProvider` which `FormLabel` and `FormMessage` use internally.

## Less boilerplate [#less-boilerplate]

React Hook Form's standard approach uses render props to access field state, plus extra state to wire the visibility toggle:

```tsx
const [showPassword, setShowPassword] = useState(false);

<FormField
  control={form.control}
  name="password"
  render={({ field }) => (
    <FormItem>
      <FormLabel>Password</FormLabel>
      <FormControl>
        <InputGroup>
          <InputGroupInput type={showPassword ? 'text' : 'password'} {...field} />
          <InputGroupAddon align='inline-end'>
            <InputGroupButton onClick={() => setShowPassword((v) => !v)}>
              {showPassword ? <EyeOff /> : <Eye />}
            </InputGroupButton>
          </InputGroupAddon>
        </InputGroup>
      </FormControl>
      <FormMessage />
    </FormItem>
  )}
/>
```

With `PasswordField`, this reduces to a single declarative component:

```tsx
<PasswordField
  lens={lens.focus('password')}
  label="Password"
  tooltip='Must contain: 8+ characters, uppercase, number, special char'
/>
```

## Examples [#examples]

## Props [#props]

# Radio Field (/components/react-hook-form/radio-field)

`RadioField` is a radio button group component that encapsulates React Hook Form's field management with shadcn/ui's design system. It handles all the boilerplate of connecting form state to a radio group: rendering each option, wiring event handlers, displaying errors, and providing accessible labels.

#### Built-in features [#built-in-features]

* **Typed lens binding**: `lens.focus('plan')` autocompletes from your form's value type — no `<MyForm>` generic at the call site
* **Automatic option rendering**: pass an array of strings and get fully functional radio buttons
* **Consistent layout**: pre-configured spacing and alignment for radio groups
* **Accessibility support**: proper ARIA attributes, label associations, and keyboard navigation
* **Zod validation**: native integration with react-hook-form and Zod via resolver

## Setup [#setup]

Field components bind via `@hookform/lenses`. Create a lens once per form:

```tsx
import { useLens } from '@hookform/lenses';
import { useForm } from 'react-hook-form';
import { Form } from '@/components/ui/form';
import { RadioField } from '@/components/ui/shuip/react-hook-form/radio-field';

const form = useForm<MyForm>({ defaultValues: { plan: 'free' } });
const lens = useLens({ control: form.control });

<Form {...form}>
  <form onSubmit={form.handleSubmit(onSubmit)}>
    <RadioField lens={lens.focus('plan')} options={['free', 'pro', 'enterprise']} label='Plan' />
  </form>
</Form>
```

The `<Form>` wrapper is required — it provides shadcn's `FormProvider` which `FormLabel` and `FormMessage` use internally.

## Less boilerplate [#less-boilerplate]

React Hook Form's standard approach uses render props to access field state:

```tsx
<FormField
  control={form.control}
  name='plan'
  render={({ field }) => (
    <FormItem className='space-y-3'>
      <FormLabel>Select a plan</FormLabel>
      <FormControl>
        <RadioGroup
          value={field.value ?? ''}
          onValueChange={field.onChange}
          className='flex flex-col space-y-1'
        >
          <FormItem className='flex items-center space-x-3 space-y-0'>
            <FormControl>
              <RadioGroupItem value='free' />
            </FormControl>
            <FormLabel className='font-normal'>free</FormLabel>
          </FormItem>
          <FormItem className='flex items-center space-x-3 space-y-0'>
            <FormControl>
              <RadioGroupItem value='pro' />
            </FormControl>
            <FormLabel className='font-normal'>pro</FormLabel>
          </FormItem>
          <FormItem className='flex items-center space-x-3 space-y-0'>
            <FormControl>
              <RadioGroupItem value='enterprise' />
            </FormControl>
            <FormLabel className='font-normal'>enterprise</FormLabel>
          </FormItem>
        </RadioGroup>
      </FormControl>
      <FormMessage />
    </FormItem>
  )}
/>
```

With `RadioField`, this reduces to a single declarative component:

```tsx
<RadioField
  lens={lens.focus('plan')}
  options={['free', 'pro', 'enterprise']}
  label='Select a plan'
/>
```

## Examples [#examples]

## Props [#props]

<TypeTable
  type="{
  lens: {
    description: 'Typed lens from useLens (see Setup section).',
    type: 'Lens<string>',
  },
  options: {
    description: 'Array of options to render as radio buttons',
    type: 'string[]',
  },
  label: {
    description: 'Label displayed above the radio group',
    type: 'string?',
  },
  description: {
    description: 'Optional description below the field',
    type: 'string?',
  },
  "...props": {
    description: 'All shadcn/ui RadioGroup props',
    type: 'RadioGroupProps',
  },
}"
/>

# Select Field (/components/react-hook-form/select-field)

`SelectField` is a single-choice dropdown component that encapsulates React Hook Form's field management with shadcn/ui's design system. It handles wiring the controlled value, change handler, validation state, and option rendering from a key-value map.

#### Built-in features [#built-in-features]

* **Typed lens binding**: `lens.focus('country')` autocompletes from your form's value type — no `<MyForm>` generic at the call site
* **Automatic option rendering**: pass a `Record<string, string>` — keys become labels, values become form data
* **Controlled value**: bound through `value`/`onValueChange`, kept in sync with form state
* **Zod validation**: native integration with react-hook-form and Zod via resolver
* **Accessibility**: full keyboard navigation and screen reader support via Radix Select

## Setup [#setup]

Field components bind via `@hookform/lenses`. Create a lens once per form:

```tsx
import { useLens } from '@hookform/lenses';
import { useForm } from 'react-hook-form';
import { Form } from '@/components/ui/form';
import { SelectField } from '@/components/ui/shuip/react-hook-form/select-field';

const form = useForm<MyForm>({ defaultValues: { country: 'us' } });
const lens = useLens({ control: form.control });

<Form {...form}>
  <form onSubmit={form.handleSubmit(onSubmit)}>
    <SelectField
      lens={lens.focus('country')}
      label='Country'
      options={{ 'United States': 'us', Canada: 'ca', France: 'fr' }}
    />
  </form>
</Form>
```

The `<Form>` wrapper is required — it provides shadcn's `FormProvider` which `FormLabel` and `FormMessage` use internally. Default selections belong on `useForm({ defaultValues })`, not on the field component.

## Less boilerplate [#less-boilerplate]

React Hook Form's standard approach uses render props to access field state:

```tsx
<FormField
  control={form.control}
  name="country"
  render={({ field }) => (
    <FormItem>
      <FormLabel>Country</FormLabel>
      <Select onValueChange={field.onChange} value={field.value}>
        <FormControl>
          <SelectTrigger>
            <SelectValue placeholder="Select a country" />
          </SelectTrigger>
        </FormControl>
        <SelectContent>
          <SelectItem value="us">United States</SelectItem>
          <SelectItem value="ca">Canada</SelectItem>
          <SelectItem value="fr">France</SelectItem>
        </SelectContent>
      </Select>
      <FormDescription>
        Choose your country
      </FormDescription>
      <FormMessage />
    </FormItem>
  )}
/>
```

With `SelectField`, this reduces to a single declarative component:

```tsx
<SelectField
  lens={lens.focus('country')}
  label='Country'
  placeholder='Select a country'
  description='Choose your country'
  options={{ 'United States': 'us', Canada: 'ca', France: 'fr' }}
/>
```

## Examples [#examples]

## Props [#props]

<TypeTable
  type="{
  lens: {
    description: 'Typed lens from useLens (see Setup section). Field value must be a string.',
    type: 'Lens<string>',
  },
  options: {
    description: 'Object where keys are labels (displayed to users) and values are form values (stored in form data).',
    type: 'Record<string, string>',
  },
  label: {
    description: 'Field label text',
    type: 'string?',
  },
  placeholder: {
    description: 'Placeholder text shown when no option is selected',
    type: 'string?',
  },
  description: {
    description: 'Helper text displayed below the select',
    type: 'string?',
  },
  props: {
    description: 'Radix Select props — spread on the underlying Select, except value/onValueChange which are managed.',
    type: 'SelectProps',
  },
}"
/>

# Textarea Field (/components/react-hook-form/textarea-field)

`TextareaField` is a multi-line text input component that encapsulates React Hook Form's field management with shadcn/ui's design system. It handles all the boilerplate of connecting form state to a textarea element: wiring event handlers, displaying errors, managing touched states, and rendering consistent UI.

#### Built-in features [#built-in-features]

* **Typed lens binding**: `lens.focus('bio')` autocompletes from your form's value type — no `<MyForm>` generic at the call site
* **Bottom-right tooltip**: optional InfoIcon button with tooltip content via `tooltip` prop, positioned via InputGroup `align='block-end'`
* **Native textarea props**: full support for `rows`, `maxLength`, `placeholder`, and other native attributes
* **InputGroup ready**: built on shadcn InputGroup for seamless addon integration
* **Zod validation**: native integration with react-hook-form and Zod via resolver

## Setup [#setup]

Field components bind via `@hookform/lenses`. Create a lens once per form:

```tsx
import { useLens } from '@hookform/lenses';
import { useForm } from 'react-hook-form';
import { Form } from '@/components/ui/form';
import { TextareaField } from '@/components/ui/shuip/react-hook-form/textarea-field';

const form = useForm<MyForm>({ defaultValues: { bio: '' } });
const lens = useLens({ control: form.control });

<Form {...form}>
  <form onSubmit={form.handleSubmit(onSubmit)}>
    <TextareaField lens={lens.focus('bio')} label='Bio' />
  </form>
</Form>
```

The `<Form>` wrapper is required — it provides shadcn's `FormProvider` which `FormLabel` and `FormMessage` use internally.

## Less boilerplate [#less-boilerplate]

React Hook Form's standard approach uses render props to access field state:

```tsx
<FormField
  control={form.control}
  name="bio"
  render={({ field }) => (
    <FormItem>
      <FormLabel>Bio</FormLabel>
      <FormControl>
        <Textarea placeholder="Tell us about yourself..." rows={4} {...field} />
      </FormControl>
      <FormDescription>
        Tell us about yourself
      </FormDescription>
      <FormMessage />
    </FormItem>
  )}
/>
```

With `TextareaField`, this reduces to a single declarative component:

```tsx
<TextareaField
  lens={lens.focus('bio')}
  label="Bio"
  description="Tell us about yourself"
  placeholder="Tell us about yourself..."
  rows={4}
/>
```

## Examples [#examples]

## Props [#props]

<TypeTable
  type="{
  lens: {
    description: 'Typed lens from useLens (see Setup section).',
    type: 'Lens<string>',
  },
  label: {
    description: 'Field label text',
    type: 'string?',
  },
  description: {
    description: 'Helper text displayed below the textarea',
    type: 'string?',
  },
  tooltip: {
    description: 'Tooltip content displayed in an info icon button at bottom-right',
    type: 'React.ReactNode?',
  },
  props: {
    description: 'Native HTML textarea props (rows, maxLength, placeholder, etc.) — spread on InputGroupTextarea, except value/onChange which are managed.',
    type: "Omit<React.ComponentProps<typeof Textarea>, 'value' | 'onChange'>",
  },
}"
/>

# Time Field (/components/react-hook-form/time-field)

`TimeField` is a time-only picker built from two shadcn/ui `Select` inputs — hours `00`–`23` and minutes in 5-minute steps. It binds to a `string` in the `HH:mm` 24-hour format, encapsulating React Hook Form's field management.

#### Built-in features [#built-in-features]

* **Two-select picker**: hours and minutes as shadcn `Select` inputs — consistent styling, full keyboard support, no native-input inconsistencies across browsers
* **Typed lens binding**: `lens.focus('meetingTime')` autocompletes from your form's value type
* **Range constraints**: pass `min` / `max` (as `HH:mm` strings) to disable out-of-range hour and minute options
* **Zod validation**: native integration with react-hook-form and Zod via resolver

## Setup [#setup]

Field components bind via `@hookform/lenses`. Create a lens once per form:

```tsx
import { useLens } from '@hookform/lenses';
import { useForm } from 'react-hook-form';
import { Form } from '@/components/ui/form';
import { TimeField } from '@/components/ui/shuip/react-hook-form/time-field';

const form = useForm<MyForm>({ defaultValues: { meetingTime: '' } });
const lens = useLens({ control: form.control });

<Form {...form}>
  <form onSubmit={form.handleSubmit(onSubmit)}>
    <TimeField lens={lens.focus('meetingTime')} label='Meeting time' />
  </form>
</Form>
```

The value is a `string` in `HH:mm` format (or empty string when unset). Picking only the hour or only the minute defaults the other part to `00`.

## Constraining the range [#constraining-the-range]

`min` and `max` accept `HH:mm` strings. Out-of-range hour and minute options are disabled in the dropdowns. Always validate via Zod (and server-side) for safety:

```tsx
const schema = z.object({
  appointment: z
    .string()
    .min(1, 'Required')
    .refine((v) => v >= '09:00' && v <= '18:00', 'Outside office hours'),
});

<TimeField lens={lens.focus('appointment')} label='Appointment' min='09:00' max='18:00' />
```

## Examples [#examples]

## Props [#props]

<TypeTable
  type="{
  lens: {
    description: 'Typed lens from useLens (see Setup section). Bound to a HH:mm string.',
    type: 'Lens<string>',
  },
  label: {
    description: 'Field label text',
    type: 'string?',
  },
  description: {
    description: 'Helper text displayed below the picker',
    type: 'string?',
  },
  min: {
    description: 'Earliest selectable time as a HH:mm string. Out-of-range options are disabled.',
    type: 'string?',
  },
  max: {
    description: 'Latest selectable time as a HH:mm string. Out-of-range options are disabled.',
    type: 'string?',
  },
  disabled: {
    description: 'Disables both selects',
    type: 'boolean?',
  },
}"
/>

# Time Range (/components/react-hook-form/time-range)

`TimeRangeField` is two coupled time pickers — a start and an end — bound to a single `{ start, end }` object via a typed lens from [`@hookform/lenses`](https://github.com/react-hook-form/lenses). Both values are `HH:mm` strings.

#### Built-in features [#built-in-features]

* **Coupled pickers**: choosing a start time sets the end to one hour later automatically
* **`start < end` enforced**: end options at or before the start are disabled in the dropdowns
* **Single object binding**: `lens.focus('slot')` binds the whole `{ start, end }` value
* **Zod validation**: refine the object to require a valid ordered range

## Setup [#setup]

```tsx
import { useLens } from '@hookform/lenses';
import { useForm } from 'react-hook-form';
import { Form } from '@/components/ui/form';
import { TimeRangeField } from '@/components/ui/shuip/react-hook-form/time-range';

type MyForm = { slot: { start: string; end: string } };

const form = useForm<MyForm>({ defaultValues: { slot: { start: '', end: '' } } });
const lens = useLens({ control: form.control });

<Form {...form}>
  <form onSubmit={form.handleSubmit(onSubmit)}>
    <TimeRangeField lens={lens.focus('slot')} label='Meeting slot' />
  </form>
</Form>
```

The value is `{ start: string; end: string }`, each a `HH:mm` string (empty when unset). Changing the start always resets the end to one hour after the new start.

## Examples [#examples]

## Props [#props]

<TypeTable
  type="{
  lens: {
    description: 'Typed lens from useLens, bound to a { start, end } object of HH:mm strings.',
    type: 'Lens<{ start: string; end: string }>',
  },
  label: {
    description: 'Field label text',
    type: 'string?',
  },
  description: {
    description: 'Helper text displayed below the pickers',
    type: 'string?',
  },
  startLabel: {
    description: 'Label above the start picker',
    type: "string? (default 'Start')",
  },
  endLabel: {
    description: 'Label above the end picker',
    type: "string? (default 'End')",
  },
  disabled: {
    description: 'Disables all selects',
    type: 'boolean?',
  },
}"
/>

# Autocomplete Field (/components/tanstack-form/autocomplete-field)

`AutocompleteField` is a text input that proposes matching strings as the user types, while still allowing any free-text value. It reads the surrounding field via `useFieldContext`, so you compose it inside a `<form.AppField>` rather than passing a `form` instance by prop. It stores a plain `string`.

#### Built-in features [#built-in-features]

## Setup [#setup]

Field components are bound via React context. In your project, create `lib/form.ts` once:

```tsx
// lib/form.ts
import { createFormHook } from '@tanstack/react-form';
import { fieldContext, formContext } from '@/components/ui/shuip/tanstack-form/form-context';
import { AutocompleteField } from '@/components/ui/shuip/tanstack-form/autocomplete-field';
import { SubmitButton } from '@/components/ui/shuip/tanstack-form/submit-button';

export const { useAppForm } = createFormHook({
  fieldContext,
  formContext,
  fieldComponents: { AutocompleteField },
  formComponents: { SubmitButton },
});
```

See the [`form-context`](/components/tanstack-form/form-context) item for details.

## Examples [#examples]

## Props [#props]

<TypeTable
  type="{
  label: {
    description: 'Field label text',
    type: 'string?',
  },
  description: {
    description: 'Helper text displayed below the input',
    type: 'string?',
  },
  placeholder: {
    description: 'Input placeholder',
    type: 'string?',
  },
  suggestions: {
    description: 'Static list of suggestions, filtered client-side. Ignored when onSearch is provided.',
    type: 'string[]?',
  },
  onSearch: {
    description: 'Async resolver called with the current query; its result is shown as-is. Takes precedence over suggestions.',
    type: '((query: string) => Promise<string[]>)?',
  },
  emptyText: {
    description: 'Message shown when there are no matches',
    type: 'string?',
    default: "'No results'",
  },
  debounceMs: {
    description: 'Debounce delay before calling onSearch (async mode only)',
    type: 'number?',
    default: '300',
  },
  filter: {
    description: 'Custom matcher for static mode; defaults to case-insensitive substring',
    type: '((suggestion: string, query: string) => boolean)?',
  },
  fieldProps: {
    description: 'Props passed to the Field wrapper component',
    type: 'React.ComponentProps<typeof Field>?',
  },
  props: {
    description: 'Native HTML input props (placeholder, disabled, etc.)',
    type: "Omit<React.ComponentProps<'input'>, 'value' | 'onChange'>?",
  },
}"
/>

# Checkbox Field (/components/tanstack-form/checkbox-field)

Checkboxes are binary inputs for opting in or accepting terms. `CheckboxField` combines Radix UI's Checkbox with an inline clickable label, making the entire label area interactive — not just the checkbox itself.

The component reads the surrounding field via `useFieldContext`, so you compose it inside a `<form.AppField>`. Common patterns include required checkboxes for terms acceptance (validated with `!value` check) or grouped checkboxes for multi-select options (using nested field paths like `features.notifications`).

### Built-in features [#built-in-features]

* **Context-bound field state** via `useFieldContext` — no prop drilling
* **Clickable inline label** positioned next to checkbox
* **Boolean field type** for true/false state
* **Required validation** for terms acceptance
* **Nested paths** for grouped checkboxes

## Setup [#setup]

Field components are bound via React context. In your project, create `lib/form.ts` once:

```tsx
// lib/form.ts
import { createFormHook } from '@tanstack/react-form';
import { fieldContext, formContext } from '@/components/ui/shuip/tanstack-form/form-context';
import { CheckboxField } from '@/components/ui/shuip/tanstack-form/checkbox-field';
import { SubmitButton } from '@/components/ui/shuip/tanstack-form/submit-button';

export const { useAppForm } = createFormHook({
  fieldContext,
  formContext,
  fieldComponents: { CheckboxField },
  formComponents: { SubmitButton },
});
```

See the [`form-context`](/components/tanstack-form/form-context) item for details.

## Required checkbox [#required-checkbox]

```tsx
import { useAppForm } from '@/lib/form';

const form = useAppForm({
  defaultValues: { terms: false },
  onSubmit: async ({ value }) => {
    await saveData(value);
  },
});

<form.AppField
  name='terms'
  validators={{
    onChange: ({ value }) =>
      !value ? 'You must accept the terms' : undefined,
  }}
  children={(field) => (
    <field.CheckboxField label='I accept the terms and conditions' />
  )}
/>
```

## Examples [#examples]

## Props [#props]

<TypeTable
  type="{
  label: {
    description: 'Clickable label displayed next to the checkbox (required)',
    type: 'string',
  },
  description: {
    description: 'Helper text displayed below the checkbox',
    type: 'string?',
  },
  fieldProps: {
    description: 'Props passed to the Field wrapper component',
    type: 'React.ComponentProps<typeof Field>?',
  },
  props: {
    description: 'Props passed to the Checkbox component',
    type: 'React.ComponentProps<typeof Checkbox>?',
  },
}"
/>

# Date Field (/components/tanstack-form/date-field)

`DateField` is a single-date picker that encapsulates TanStack Form's field management with the shadcn `Calendar` primitive. The trigger is an outline `Button` (full-width) that shows the selected date formatted via [`date-fns`](https://date-fns.org); clicking it opens a `Popover` containing the calendar.

It reads the surrounding field via `useFieldContext<Date | undefined>()`, so you compose it inside a `<form.AppField>` rather than passing a `form` instance down. `undefined` represents an empty selection (matching `react-day-picker`'s convention).

#### Built-in features [#built-in-features]

* **Context-bound field state**: reads the field via `useFieldContext` — no prop drilling
* **Locale-aware formatting**: defaults to `en-US`; pass any `date-fns/locale` via the `locale` prop
* **Bounded selection**: `minDate` / `maxDate` disable days outside the range in the calendar UI
* **Accessible trigger**: a real `<Button>` with `aria-invalid` reflecting `!isValid`
* **Validator-friendly**: works with TanStack Form's native validators or any standard schema

## Setup [#setup]

Field components are bound via React context. In your project, create `lib/form.ts` once:

```tsx
// lib/form.ts
import { createFormHook } from '@tanstack/react-form';
import { fieldContext, formContext } from '@/components/ui/shuip/tanstack-form/form-context';
import { DateField } from '@/components/ui/shuip/tanstack-form/date-field';
import { SubmitButton } from '@/components/ui/shuip/tanstack-form/submit-button';

export const { useAppForm } = createFormHook({
  fieldContext,
  formContext,
  fieldComponents: { DateField },
  formComponents: { SubmitButton },
});
```

See the [`form-context`](/components/tanstack-form/form-context) item for details.

Then compose the field inside `<form.AppField>`:

```tsx
import { useAppForm } from '@/lib/form';

const form = useAppForm({
  defaultValues: { dueDate: undefined as Date | undefined },
  onSubmit: async ({ value }) => saveData(value),
});

<form.AppField
  name='dueDate'
  validators={{
    onChange: ({ value }) => (value ? undefined : 'Pick a due date'),
  }}
  children={(field) => <field.DateField label='Due date' />}
/>
```

## Bounded selection [#bounded-selection]

Use `minDate` and `maxDate` to disable out-of-range days directly in the calendar:

```tsx
<form.AppField
  name='appointment'
  children={(field) => (
    <field.DateField label='Appointment' minDate={new Date()} maxDate={oneYearFromNow} />
  )}
/>
```

Disabled days remain visible but cannot be selected. Mirror the bounds in your validator so submission also rejects out-of-range values.

## Examples [#examples]

## Props [#props]

<TypeTable
  type="{
  label: {
    description: 'Field label text',
    type: 'string?',
  },
  description: {
    description: 'Helper text displayed below the trigger',
    type: 'string?',
  },
  placeholder: {
    description: 'Text shown on the trigger when no date is selected',
    type: 'string?',
    default: "'Pick a date'",
  },
  minDate: {
    description: 'Earliest selectable date (inclusive). Days before are disabled.',
    type: 'Date?',
  },
  maxDate: {
    description: 'Latest selectable date (inclusive). Days after are disabled.',
    type: 'Date?',
  },
  locale: {
    description: 'date-fns locale used for formatting and weekday labels',
    type: 'Locale?',
    default: 'enUS',
  },
  dateFormat: {
    description: 'date-fns format string for the trigger label',
    type: 'string?',
    default: "'PPP'",
  },
  disabled: {
    description: 'Disables the trigger button',
    type: 'boolean?',
  },
  fieldProps: {
    description: 'Props passed to the Field wrapper component',
    type: 'React.ComponentProps<typeof Field>?',
  },
  triggerProps: {
    description: 'Additional props forwarded to the trigger Button',
    type: 'React.ComponentProps<typeof Button>?',
  },
}"
/>

# Date Range Field (/components/tanstack-form/date-range-field)

`DateRangeField` is a from–to date picker bound to TanStack Form. It wraps the shadcn `Calendar` primitive in `mode='range'` inside a `Popover`, and reads the surrounding field via `useFieldContext` — compose it inside a `<form.AppField>` rather than passing a `form` instance down by prop.

The bound value is a `DateRange` from `react-day-picker`:

```ts
type DateRange = { from?: Date; to?: Date } | undefined;
```

#### Built-in features [#built-in-features]

* **Context-bound field state**: reads the field via `useFieldContext` — no prop drilling
* **Type-safe field names**: `name` autocompletes from your `defaultValues` on `<form.AppField>`
* **Two-month side-by-side display**: canonical UX for picking a range that crosses months
* **Bounded selection**: `minDate` / `maxDate` translate to the Calendar `disabled` matcher
* **Locale aware**: optional `date-fns` `Locale` passed through to label formatting and Calendar

## Setup [#setup]

Register the field component once on your `useAppForm` factory. See the [`form-context`](/components/tanstack-form/form-context) item for details.

```tsx
// lib/form.ts
import { createFormHook } from '@tanstack/react-form';
import { fieldContext, formContext } from '@/components/ui/shuip/tanstack-form/form-context';
import { DateRangeField } from '@/components/ui/shuip/tanstack-form/date-range-field';
import { SubmitButton } from '@/components/ui/shuip/tanstack-form/submit-button';

export const { useAppForm } = createFormHook({
  fieldContext,
  formContext,
  fieldComponents: { DateRangeField },
  formComponents: { SubmitButton },
});
```

Then declare the field value type as `DateRange | undefined`:

```tsx
import type { DateRange } from 'react-day-picker';

const form = useAppForm({
  defaultValues: { stay: undefined } as { stay: DateRange | undefined },
  onSubmit: async ({ value }) => { /* ... */ },
});

<form.AppField
  name='stay'
  children={(field) => <field.DateRangeField label='Stay' />}
/>
```

## Trigger label [#trigger-label]

The trigger button renders a label derived from the current value:

* both ends set → `"<from> – <to>"` using `date-fns` `format(date, 'PPP', { locale })`
* only `from` set → just the `from` date
* neither set → the `placeholder` prop

## Validation [#validation]

Validation lives on `<form.AppField>` as with any TanStack field. To require both ends of the range and enforce ordering:

```tsx
<form.AppField
  name='booking'
  validators={{
    onChange: ({ value }) => {
      if (!value?.from) return 'Start date is required';
      if (!value.to) return 'End date is required';
      if (value.to < value.from) return 'End date must be on or after the start date';
      return undefined;
    },
  }}
  children={(field) => <field.DateRangeField label='Booking' />}
/>
```

## Examples [#examples]

## Props [#props]

<TypeTable
  type="{
  label: {
    description: 'Field label text',
    type: 'string?',
  },
  description: {
    description: 'Helper text displayed below the trigger',
    type: 'string?',
  },
  placeholder: {
    description: 'Trigger label when no date is selected (default: "Pick a date range")',
    type: 'string?',
  },
  minDate: {
    description: 'Earliest selectable date — passed to Calendar as disabled.before',
    type: 'Date?',
  },
  maxDate: {
    description: 'Latest selectable date — passed to Calendar as disabled.after',
    type: 'Date?',
  },
  locale: {
    description: 'date-fns Locale used for label formatting and the Calendar',
    type: 'Locale?',
  },
  fieldProps: {
    description: 'Props passed to the Field wrapper component',
    type: 'React.ComponentProps<typeof Field>?',
  },
  triggerProps: {
    description: 'Props passed to the trigger Button (variant, size, className, etc.)',
    type: 'React.ComponentProps<typeof Button>?',
  },
}"
/>

# Datetime Field (/components/tanstack-form/datetime-field)

`DatetimeField` is a single-value date + time picker that stores its selection as one `Date` carrying both the day and the hours/minutes. It wraps shadcn's `Calendar` and a native `<input type="time">` inside a `Popover`, and reads the surrounding field via `useFieldContext` from your `useAppForm` setup.

For date-only fields, use `Calendar` directly. This component is for cases where the time of day matters as much as the date — meeting start, deadline, deliverable, etc.

#### Built-in features [#built-in-features]

* **Single `Date` value**: day + hours + minutes live in one field — no separate date/time pieces to reconcile
* **Context-bound field state**: reads the field via `useFieldContext` — no prop drilling
* **Locale-aware label**: trigger renders via `date-fns` `format(value, 'PPp', { locale })`
* **Bounds**: `minDate` / `maxDate` disable out-of-range days on the calendar
* **Time step**: native `<input type="time" step="...">` for minute or second granularity

## Setup [#setup]

```tsx
// lib/form.ts
import { createFormHook } from '@tanstack/react-form';
import { fieldContext, formContext } from '@/components/ui/shuip/tanstack-form/form-context';
import { DatetimeField } from '@/components/ui/shuip/tanstack-form/datetime-field';
import { SubmitButton } from '@/components/ui/shuip/tanstack-form/submit-button';

export const { useAppForm } = createFormHook({
  fieldContext,
  formContext,
  fieldComponents: { DatetimeField },
  formComponents: { SubmitButton },
});
```

See the [`form-context`](/components/tanstack-form/form-context) item for details.

Then compose it inside `<form.AppField>`:

```tsx
const form = useAppForm({
  defaultValues: { scheduledAt: undefined as Date | undefined },
  onSubmit: async ({ value }) => save(value),
});

<form.AppField
  name='scheduledAt'
  children={(field) => <field.DatetimeField label='Scheduled at' />}
/>
```

When the field's value can be `undefined`, type the default value with an assertion as shown — TanStack Form infers `Date | undefined` from it.

## Behavior [#behavior]

## Examples [#examples]

## Props [#props]

# Form Context (/components/tanstack-form/form-context)

`form-context` exports the React contexts and consumer hooks produced by TanStack Form's `createFormHookContexts()`. It is the foundation for the context-bound composition pattern: reusable field and form components read their state from React context instead of receiving the `form` instance as a prop.

This sidesteps the variance problem that arises when `ReactFormApi`'s eleven validator generics need to cross a component boundary — the same problem that forces `form={form as any}` casts in the prop-drilling pattern.

## What you install [#what-you-install]

```tsx
// components/ui/shuip/tanstack-form/form-context.tsx
'use client';

import { createFormHookContexts } from '@tanstack/react-form';

export const { fieldContext, formContext, useFieldContext, useFormContext } = createFormHookContexts();
```

Four exports:

* **`fieldContext`**, **`formContext`** — pass these to `createFormHook` in your project setup.
* **`useFieldContext<T>()`** — call inside a field component to read `field` (state, errors, handlers). The generic asserts the field value type.
* **`useFormContext()`** — call inside a form-level component (submit buttons, layout chrome) to read the form instance.

## Project setup [#project-setup]

Create a `lib/form.ts` in your project that calls `createFormHook` once, binding every field and form component you want available globally.

```tsx
// lib/form.ts
import { createFormHook } from '@tanstack/react-form';
import { fieldContext, formContext } from '@/components/ui/shuip/tanstack-form/form-context';

import { TextField } from '@/components/ui/my-text-field';
import { SubmitButton } from '@/components/ui/my-submit-button';

export const { useAppForm, withForm, withFieldGroup } = createFormHook({
  fieldContext,
  formContext,
  fieldComponents: { TextField },
  formComponents: { SubmitButton },
});
```

Consumer usage:

```tsx
import { useAppForm } from '@/lib/form';
import { z } from 'zod';

const schema = z.object({ username: z.string().min(3) });

function MyForm() {
  const form = useAppForm({
    defaultValues: { username: '' },
    validators: { onChange: schema },
    onSubmit: ({ value }) => console.log(value),
  });

return (
    <form onSubmit={(e) => { e.preventDefault(); form.handleSubmit(); }}>
      <form.AppField name='username' children={(field) => <field.TextField label='Username' />} />
      <form.AppForm><form.SubmitButton>Submit</form.SubmitButton></form.AppForm>
    </form>
  );
}
```

The `name` is autocompleted from `defaultValues`. Validators accept any standard schema (Zod, Valibot, ArkType) or a plain function.

## Building a field component [#building-a-field-component]

A field component consumes the field via `useFieldContext`. It never receives `form` or `name` as a prop — both come from the surrounding `<form.AppField>`.

```tsx
'use client';

import { useFieldContext } from '@/components/ui/shuip/tanstack-form/form-context';
import { Input } from '@/components/ui/input';

export function TextField({ label }: { label: string }) {
  const field = useFieldContext<string>();
  return (
    <label>
      {label}
      <Input
        value={field.state.value}
        onChange={(e) => field.handleChange(e.target.value)}
        onBlur={field.handleBlur}
        aria-invalid={!field.state.meta.isValid}
      />
    </label>
  );
}
```

## Example [#example]

## Exports [#exports]

<TypeTable
  type="{
  fieldContext: {
    description: 'React context used by TanStack to thread the field API to children of form.AppField.',
    type: 'Context<unknown>',
  },
  formContext: {
    description: 'React context used by TanStack to thread the form API to children of form.AppForm.',
    type: 'Context<unknown>',
  },
  useFieldContext: {
    description: 'Read the current field inside a custom field component. The generic asserts the field value type.',
    type: '<T>() => FieldApi<T, ...>',
  },
  useFormContext: {
    description: 'Read the current form inside a custom form-level component (submit buttons, layout chrome).',
    type: '() => FormApi<...>',
  },
}"
/>

# Inline Edit Field (/components/tanstack-form/inline-edit)

A click-to-edit field for TanStack Form. The value displays as text and turns into an
editable input on click; read and edit share one typography scale, so editing is seamless.
On each commit the field writes its value to the form and validates it — an invalid value
keeps the field in edit mode with the error shown inline.

When the value is valid the field triggers the form's submit, so your `onSubmit` handler
persists it (the field shows a saving indicator while it runs). The example below stores the
whole form in `localStorage` from `onSubmit`, so one handler covers every field.

## Examples [#examples]

## Props [#props]

# Input Field (/components/tanstack-form/input-field)

`InputField` is a text input component that encapsulates TanStack Form's field management with shadcn/ui's design system. It handles all the boilerplate of connecting form state to an input element: wiring event handlers, displaying errors, managing touched states, and rendering consistent UI.

It reads the surrounding field via `useFieldContext`, so you compose it inside a `<form.AppField>` rather than passing a `form` instance down by prop.

#### Built-in features [#built-in-features]

* **Context-bound field state**: reads the field via `useFieldContext` — no prop drilling
* **Type-safe field names**: `name` autocompletes from your `defaultValues` on `<form.AppField>`
* **Tooltip integration**: optional InfoIcon button with tooltip content via `tooltip` prop
* **InputGroup ready**: supports shadcn InputGroup for seamless addon integration
* **Async validation**: built-in debouncing and loading states for API validation

## Setup [#setup]

Field components are bound via React context. In your project, create `lib/form.ts` once:

```tsx
// lib/form.ts
import { createFormHook } from '@tanstack/react-form';
import { fieldContext, formContext } from '@/components/ui/shuip/tanstack-form/form-context';
import { InputField } from '@/components/ui/shuip/tanstack-form/input-field';
import { SubmitButton } from '@/components/ui/shuip/tanstack-form/submit-button';

export const { useAppForm } = createFormHook({
  fieldContext,
  formContext,
  fieldComponents: { InputField },
  formComponents: { SubmitButton },
});
```

See the [`form-context`](/components/tanstack-form/form-context) item for details.

## Less boilerplate [#less-boilerplate]

TanStack Form's standard approach uses render props to access field state:

```tsx
<form.Field
  name='email'
  validators={{
    onChange: ({ value }) => !value.includes('@') ? 'Invalid email' : undefined,
  }}
>
  {(field) => (
    <>
      <label htmlFor={field.name}>Email</label>
      <input
        id={field.name}
        name={field.name}
        type='email'
        value={field.state.value}
        onChange={(e) => field.handleChange(e.target.value)}
        onBlur={field.handleBlur}
      />
      {!field.state.meta.isValid && (
        <span>{field.state.meta.errors.join(', ')}</span>
      )}
    </>
  )}
</form.Field>
```

With `InputField` mounted inside `<form.AppField>`, the same field reduces to:

```tsx
<form.AppField
  name='email'
  validators={{
    onChange: ({ value }) => !value.includes('@') ? 'Invalid email' : undefined,
  }}
  children={(field) => (
    <field.InputField label='Email' props={{ type: 'email' }} />
  )}
/>
```

The `name` and validators live on `<form.AppField>`; the wrapper just removes the inline JSX boilerplate for label, error display, and event wiring.

## Common use cases [#common-use-cases]

```tsx
import { useAppForm } from '@/lib/form';

const form = useAppForm({
  defaultValues: {
    name: '',
    email: '',
    username: '',
    age: 0,
  },
  onSubmit: async ({ value }) => {
    await saveData(value);
  },
});

// Basic text input
<form.AppField
  name='name'
  children={(field) => (
    <field.InputField label='Name' description='Your full name' />
  )}
/>

// Email with validation
<form.AppField
  name='email'
  validators={{
    onChange: ({ value }) =>
      !value.includes('@') ? 'Invalid email' : undefined,
  }}
  children={(field) => (
    <field.InputField label='Email' props={{ type: 'email' }} />
  )}
/>

// With tooltip
<form.AppField
  name='username'
  validators={{
    onChange: ({ value }) =>
      value.length < 3 ? 'Too short' : undefined,
  }}
  children={(field) => (
    <field.InputField
      label='Username'
      tooltip='Username must be unique and 3-20 characters'
    />
  )}
/>

// Numeric input — auto-detected because age is a number in defaultValues
<form.AppField
  name='age'
  children={(field) => (
    <field.InputField label='Age' props={{ min: 0, max: 120 }} />
  )}
/>
```

## Numeric fields [#numeric-fields]

`InputField` handles both string and numeric fields. It detects numeric mode when either:

* `props.type` is `'number'` or `'range'`, or
* the field's current value is a `number` (typically because `defaultValues` declares it as one)

In numeric mode the input renders as `type='number'` and writes back `e.target.valueAsNumber` — empty input becomes `NaN`, which validators can check with `Number.isNaN(value)`. In string mode it passes `e.target.value` through unchanged.

```tsx
const form = useAppForm({
  defaultValues: { quantity: 1, ratio: 0.5 },
  validators: {
    onChange: ({ value }) =>
      Number.isNaN(value.quantity) ? { fields: { quantity: 'Required' } } : undefined,
  },
});

<form.AppField name='quantity' children={(f) => <f.InputField label='Quantity' />} />
<form.AppField name='ratio'    children={(f) => <f.InputField label='Ratio' props={{ type: 'range', min: 0, max: 1, step: 0.1 }} />} />
```

If the field type is `number | undefined` / `number | null` and `defaultValues` starts as `undefined`/`null`, the runtime type check can't infer numeric mode — set `props={{ type: 'number' }}` explicitly in that case.

## Examples [#examples]

## Props [#props]

<TypeTable
  type="{
  label: {
    description: 'Field label text',
    type: 'string?',
  },
  description: {
    description: 'Helper text displayed below the input',
    type: 'string?',
  },
  tooltip: {
    description: 'Tooltip content displayed in an info icon button',
    type: 'React.ReactNode?',
  },
  fieldProps: {
    description: 'Props passed to the Field wrapper component',
    type: 'React.ComponentProps<typeof Field>?',
  },
  props: {
    description: 'Native HTML input props (type, placeholder, disabled, etc.)',
    type: "React.ComponentProps<'input'>?",
  },
}"
/>

# Month Field (/components/tanstack-form/month-field)

It reads the surrounding field via `useFieldContext<Date | undefined>()`, so you compose it inside a `<form.AppField>` rather than passing a `form` instance down by prop.

#### Built-in features [#built-in-features]

* **First-day normalization**: any day the user clicks is internally rewritten to `new Date(year, month, 1)`, so the stored value behaves as a month bucket
* **Dropdown caption**: month and year dropdowns in the calendar header (`captionLayout='dropdown'`)
* **Bounded range**: `minDate` / `maxDate` drive both the calendar's disabled days and its dropdown bounds via `startMonth` / `endMonth`
* **Locale aware**: `locale` is forwarded to `date-fns` `format` and to the calendar
* **Context-bound field state**: reads the field via `useFieldContext` — no prop drilling

## Setup [#setup]

```tsx
// lib/form.ts
import { createFormHook } from '@tanstack/react-form';
import { fieldContext, formContext } from '@/components/ui/shuip/tanstack-form/form-context';
import { MonthField } from '@/components/ui/shuip/tanstack-form/month-field';
import { SubmitButton } from '@/components/ui/shuip/tanstack-form/submit-button';

export const { useAppForm } = createFormHook({
  fieldContext,
  formContext,
  fieldComponents: { MonthField },
  formComponents: { SubmitButton },
});
```

Then bind a `Date | undefined` field:

```tsx
const form = useAppForm({
  defaultValues: { billingMonth: undefined as Date | undefined },
  onSubmit: async ({ value }) => saveBilling(value.billingMonth),
});

<form.AppField
  name='billingMonth'
  validators={{ onChange: ({ value }) => (value ? undefined : 'Required') }}
  children={(field) => <field.MonthField label='Billing month' />}
/>
```

## Value shape [#value-shape]

The stored value is always either `undefined` or a `Date` whose day component is `1`. Consumers can compare months by `value.getTime()` without worrying about time-of-day drift:

```ts
const a = new Date(2026, 4, 1);  // May 2026
const b = new Date(2026, 4, 1);  // May 2026
a.getTime() === b.getTime();     // true
```

## Examples [#examples]

## Props [#props]

<TypeTable
  type="{
  label: {
    description: 'Field label text',
    type: 'string?',
  },
  description: {
    description: 'Helper text displayed below the trigger',
    type: 'string?',
  },
  placeholder: {
    description: 'Trigger text shown when no month is selected',
    type: 'string?',
    default: "'Pick a month'",
  },
  minDate: {
    description: 'Earliest selectable month. Drives both disabled days and startMonth for the year dropdown.',
    type: 'Date?',
  },
  maxDate: {
    description: 'Latest selectable month. Drives both disabled days and endMonth for the year dropdown.',
    type: 'Date?',
  },
  locale: {
    description: 'date-fns Locale forwarded to format() and to Calendar.',
    type: 'Locale?',
  },
  disabled: {
    description: 'Disables the trigger button.',
    type: 'boolean?',
  },
  fieldProps: {
    description: 'Props passed to the Field wrapper component',
    type: 'React.ComponentProps<typeof Field>?',
  },
  className: {
    description: 'Extra classes applied to the trigger button.',
    type: 'string?',
  },
}"
/>

# Password Field (/components/tanstack-form/password-field)

Password inputs require special UX considerations: users need to verify their input while maintaining security. `PasswordField` solves this with a built-in visibility toggle (Eye/EyeOff icons) that switches between masked and plain text.

The component reads the surrounding field via `useFieldContext`, so you compose it inside a `<form.AppField>`. It uses shadcn's `InputGroup` to position the toggle button inline with the input, avoiding layout shifts. An optional tooltip can be added via the `tooltip` prop to display password requirements — this appears as an InfoIcon button next to the visibility toggle.

#### Built-in features [#built-in-features]

* **Context-bound field state** via `useFieldContext` — no prop drilling
* **One-click visibility toggle** with Eye/EyeOff icons
* **InputGroup positioning** for seamless button integration
* **Optional tooltip** for password requirements or help text
* **Linked field validation** via `onChangeListenTo` for confirmation fields

## Setup [#setup]

Field components are bound via React context. In your project, create `lib/form.ts` once:

```tsx
// lib/form.ts
import { createFormHook } from '@tanstack/react-form';
import { fieldContext, formContext } from '@/components/ui/shuip/tanstack-form/form-context';
import { PasswordField } from '@/components/ui/shuip/tanstack-form/password-field';
import { SubmitButton } from '@/components/ui/shuip/tanstack-form/submit-button';

export const { useAppForm } = createFormHook({
  fieldContext,
  formContext,
  fieldComponents: { PasswordField },
  formComponents: { SubmitButton },
});
```

See the [`form-context`](/components/tanstack-form/form-context) item for details.

## Password security patterns [#password-security-patterns]

Common validation pattern for strong passwords:

```tsx
import { useAppForm } from '@/lib/form';

const form = useAppForm({
  defaultValues: { password: '', confirmPassword: '' },
  onSubmit: async ({ value }) => {
    await saveData(value);
  },
});

<form.AppField
  name='password'
  validators={{
    onChange: ({ value }) => {
      if (value.length < 8) return 'At least 8 characters required';
      if (!/[A-Z]/.test(value)) return 'Must include uppercase letter';
      if (!/[0-9]/.test(value)) return 'Must include number';
      if (!/[!@#$%^&*]/.test(value)) return 'Must include special character';
      return undefined;
    },
  }}
  children={(field) => (
    <field.PasswordField
      label='Password'
      tooltip='Must contain: 8+ characters, uppercase, number, special char'
    />
  )}
/>
```

Confirm password with linked validation:

```tsx
<form.AppField
  name='confirmPassword'
  validators={{
    onChangeListenTo: ['password'],
    onChange: ({ value, fieldApi }) => {
      const password = fieldApi.form.getFieldValue('password');
      return value !== password ? 'Passwords do not match' : undefined;
    },
  }}
  children={(field) => (
    <field.PasswordField label='Confirm Password' />
  )}
/>
```

## Examples [#examples]

## Props [#props]

<TypeTable
  type="{
  label: {
    description: 'Field label text',
    type: 'string?',
  },
  description: {
    description: 'Helper text displayed below the input',
    type: 'string?',
  },
  tooltip: {
    description: 'Tooltip content displayed in an info icon button',
    type: 'React.ReactNode?',
  },
  fieldProps: {
    description: 'Props passed to the Field wrapper component',
    type: 'React.ComponentProps<typeof Field>?',
  },
  props: {
    description: 'Native HTML input props (placeholder, disabled, etc.)',
    type: "React.ComponentProps<'input'>?",
  },
}"
/>

# Radio Field (/components/tanstack-form/radio-field)

Radio groups let users select a single option from a list. `RadioField` uses Radix UI's RadioGroup with automatic label associations and proper ARIA attributes. Unlike `SelectField`, radio buttons show all options upfront — ideal for 2-5 choices where comparison is important.

The component reads the surrounding field via `useFieldContext`, so you compose it inside a `<form.AppField>`. The `options` prop takes an array of `{label, value}` objects, making it easy to map from data structures. Each radio button gets a unique ID combining the field name and value, ensuring proper accessibility.

### Built-in features [#built-in-features]

* **Context-bound field state** via `useFieldContext` — no prop drilling
* **Visible all-at-once** for easy comparison
* **Array-based options** with label/value structure
* **Automatic label linking** with unique IDs per option
* **Single-selection enforcement** via RadioGroup

## Setup [#setup]

Field components are bound via React context. In your project, create `lib/form.ts` once:

```tsx
// lib/form.ts
import { createFormHook } from '@tanstack/react-form';
import { fieldContext, formContext } from '@/components/ui/shuip/tanstack-form/form-context';
import { RadioField } from '@/components/ui/shuip/tanstack-form/radio-field';
import { SubmitButton } from '@/components/ui/shuip/tanstack-form/submit-button';

export const { useAppForm } = createFormHook({
  fieldContext,
  formContext,
  fieldComponents: { RadioField },
  formComponents: { SubmitButton },
});
```

See the [`form-context`](/components/tanstack-form/form-context) item for details.

## Options structure [#options-structure]

```tsx
import { useAppForm } from '@/lib/form';

const options = [
  { label: 'Display Text 1', value: 'val1' },
  { label: 'Display Text 2', value: 'val2' },
];

const form = useAppForm({
  defaultValues: { choice: '' },
  onSubmit: async ({ value }) => {
    await saveData(value);
  },
});

<form.AppField
  name='choice'
  children={(field) => (
    <field.RadioField options={options} label='Select one' />
  )}
/>
```

## Examples [#examples]

## Props [#props]

<TypeTable
  type="{
  options: {
    description: 'Array of radio button options with label and value (required)',
    type: 'Array<{ label: string; value: string }>',
  },
  label: {
    description: 'Field label text',
    type: 'string?',
  },
  description: {
    description: 'Helper text displayed below the radio group',
    type: 'string?',
  },
  fieldProps: {
    description: 'Props passed to the Field wrapper component',
    type: 'React.ComponentProps<typeof Field>?',
  },
  props: {
    description: 'Props passed to the RadioGroup component',
    type: 'React.ComponentProps<typeof RadioGroup>?',
  },
}"
/>

# Select Field (/components/tanstack-form/select-field)

Dropdowns present a list of options in a compact UI. `SelectField` uses Radix UI's Select primitive wrapped with TanStack Form state management. The `options` prop accepts a `Record<string, string>` where keys are the display labels and values are what gets stored in the form state.

The component reads the surrounding field via `useFieldContext`, so you compose it inside a `<form.AppField>`. This format makes it simple to define options inline or map from API responses. For dependent selects (e.g., country → states), use [`useStore`](https://tanstack.com/form/latest/docs/framework/react/reference/functions/usestore) to watch one field and update another field's options dynamically with `setFieldValue`.

### Built-in features [#built-in-features]

* **Context-bound field state** via `useFieldContext` — no prop drilling
* **Record-based options** for clean label/value mapping
* **Dynamic options** via state or API data
* **Dependent selects** with `form.useStore` and `setFieldValue`
* **Empty state placeholder** via `placeholder` prop

## Setup [#setup]

Field components are bound via React context. In your project, create `lib/form.ts` once:

```tsx
// lib/form.ts
import { createFormHook } from '@tanstack/react-form';
import { fieldContext, formContext } from '@/components/ui/shuip/tanstack-form/form-context';
import { SelectField } from '@/components/ui/shuip/tanstack-form/select-field';
import { SubmitButton } from '@/components/ui/shuip/tanstack-form/submit-button';

export const { useAppForm } = createFormHook({
  fieldContext,
  formContext,
  fieldComponents: { SelectField },
  formComponents: { SubmitButton },
});
```

See the [`form-context`](/components/tanstack-form/form-context) item for details.

## Options format [#options-format]

```tsx
import { useAppForm } from '@/lib/form';

const options = {
  'Display Label 1': 'value1',
  'Display Label 2': 'value2',
};

const form = useAppForm({
  defaultValues: { choice: '' },
  onSubmit: async ({ value }) => {
    await saveData(value);
  },
});

<form.AppField
  name='choice'
  children={(field) => (
    <field.SelectField
      options={options}
      label='Select an option'
      placeholder='Choose...'
    />
  )}
/>
```

## Dependent selects [#dependent-selects]

```tsx
const [states, setStates] = React.useState<Record<string, string>>({});

// Watch country changes
form.useStore((state) => state.values.country, {
  onChange: (country) => {
    setStates(country === 'us' ? { 'California': 'ca', 'Texas': 'tx' } : {});
    form.setFieldValue('state', ''); // Reset state field
  },
});

<form.AppField
  name='country'
  children={(field) => (
    <field.SelectField options={{ 'United States': 'us' }} label='Country' />
  )}
/>

<form.AppField
  name='state'
  children={(field) => (
    <field.SelectField
      options={states}
      label='State'
      placeholder='Select country first'
    />
  )}
/>
```

## Examples [#examples]

## Props [#props]

<TypeTable
  type="{
  options: {
    description: 'Options as key-value pairs where key is the label and value is the field value (required)',
    type: 'Record<string, string>',
  },
  label: {
    description: 'Field label text',
    type: 'string?',
  },
  placeholder: {
    description: 'Placeholder text shown when no value is selected',
    type: 'string?',
  },
  description: {
    description: 'Helper text displayed below the select',
    type: 'string?',
  },
  fieldProps: {
    description: 'Props passed to the Field wrapper component',
    type: 'React.ComponentProps<typeof Field>?',
  },
  props: {
    description: 'Props passed to the Select component',
    type: 'React.ComponentProps<typeof Select>?',
  },
}"
/>

# Submit Button (/components/tanstack-form/submit-button)

Submit buttons need to prevent double submissions and show loading feedback. `SubmitButton` reads the surrounding form via `useFormContext` and subscribes to its state via `form.Subscribe` to track `isSubmitting` and `canSubmit`, automatically disabling the button when the form is invalid or already submitting.

The component displays a `Loader2Icon` spinner when `isSubmitting` is true, providing visual feedback without manual state management. It accepts a `props` parameter for Button variants (outline, destructive, etc.) and all native button attributes.

Because it consumes the form via context, render it inside `<form.AppForm>` instead of passing the form down as a prop.

### Built-in features [#built-in-features]

* **Context-bound form state** via `useFormContext` — no prop drilling
* **Auto-disabled** when `!canSubmit` or `isSubmitting`
* **Loading spinner** via `Loader2Icon` during submission
* **Button variants** via `props.variant` and `props.size`

## Setup [#setup]

Field and form components are bound via React context. In your project, create `lib/form.ts` once:

```tsx
// lib/form.ts
import { createFormHook } from '@tanstack/react-form';
import { fieldContext, formContext } from '@/components/ui/shuip/tanstack-form/form-context';
import { InputField } from '@/components/ui/shuip/tanstack-form/input-field';
import { SubmitButton } from '@/components/ui/shuip/tanstack-form/submit-button';

export const { useAppForm } = createFormHook({
  fieldContext,
  formContext,
  fieldComponents: { InputField },
  formComponents: { SubmitButton },
});
```

See the [`form-context`](/components/tanstack-form/form-context) item for details.

## Usage with validation [#usage-with-validation]

```tsx
import { useAppForm } from '@/lib/form';

const form = useAppForm({
  defaultValues: { email: '' },
  onSubmit: async ({ value }) => {
    await saveData(value);
  },
});

<form.AppField
  name='email'
  validators={{
    onChange: ({ value }) => !value.includes('@') ? 'Invalid' : undefined,
  }}
  children={(field) => (
    <field.InputField label='Email' />
  )}
/>

{/* Button disabled until email is valid */}
<form.AppForm>
  <form.SubmitButton>Submit</form.SubmitButton>
</form.AppForm>
```

## Custom variants [#custom-variants]

```tsx
<form.AppForm>
  <form.SubmitButton props={{ variant: 'outline' }}>
    Save Draft
  </form.SubmitButton>
</form.AppForm>

<form.AppForm>
  <form.SubmitButton props={{ variant: 'destructive', size: 'lg' }}>
    Delete Account
  </form.SubmitButton>
</form.AppForm>
```

## Examples [#examples]

## Props [#props]

# Textarea Field (/components/tanstack-form/textarea-field)

Multi-line text inputs are essential for longer content like descriptions, comments, or messages. `TextareaField` wraps a textarea element with InputGroup to enable an optional tooltip button positioned at the bottom-right corner — useful for character limits or formatting guidelines without cluttering the label area.

The component reads the surrounding field via `useFieldContext`, so you compose it inside a `<form.AppField>`. It accepts native textarea props like `rows` and `maxLength` through the `props` parameter. Common patterns include pairing `maxLength` with a character counter (accessible via `form.useStore`) or implementing minimum length validation for meaningful input.

#### Built-in features [#built-in-features]

* **Context-bound field state** via `useFieldContext` — no prop drilling
* **Bottom-right tooltip** positioned via InputGroup `align='block-end'`
* **Native textarea props** support (rows, maxLength, placeholder)
* **Character limit validation** with min/max length validators
* **Multi-line error display** for longer validation messages

## Setup [#setup]

Field components are bound via React context. In your project, create `lib/form.ts` once:

```tsx
// lib/form.ts
import { createFormHook } from '@tanstack/react-form';
import { fieldContext, formContext } from '@/components/ui/shuip/tanstack-form/form-context';
import { TextareaField } from '@/components/ui/shuip/tanstack-form/textarea-field';
import { SubmitButton } from '@/components/ui/shuip/tanstack-form/submit-button';

export const { useAppForm } = createFormHook({
  fieldContext,
  formContext,
  fieldComponents: { TextareaField },
  formComponents: { SubmitButton },
});
```

See the [`form-context`](/components/tanstack-form/form-context) item for details.

## Length validation [#length-validation]

```tsx
import { useAppForm } from '@/lib/form';

const form = useAppForm({
  defaultValues: { feedback: '' },
  onSubmit: async ({ value }) => {
    await saveData(value);
  },
});

<form.AppField
  name='feedback'
  validators={{
    onChange: ({ value }) => {
      if (value.length < 10) return 'Please provide at least 10 characters';
      if (value.length > 500) return 'Maximum 500 characters allowed';
      return undefined;
    },
  }}
  children={(field) => (
    <field.TextareaField
      label='Feedback'
      description='Share your thoughts (10-500 characters)'
      props={{ rows: 6, maxLength: 500, placeholder: 'Your feedback...' }}
    />
  )}
/>
```

## Examples [#examples]

## Props [#props]

<TypeTable
  type="{
  label: {
    description: 'Field label text',
    type: 'string?',
  },
  description: {
    description: 'Helper text displayed below the textarea',
    type: 'string?',
  },
  tooltip: {
    description: 'Tooltip content displayed in an info icon button at bottom-right',
    type: 'React.ReactNode?',
  },
  fieldProps: {
    description: 'Props passed to the Field wrapper component',
    type: 'React.ComponentProps<typeof Field>?',
  },
  props: {
    description: 'Props passed to the InputGroupTextarea component (rows, maxLength, placeholder, etc.)',
    type: 'React.ComponentProps<typeof InputGroupTextarea>?',
  },
}"
/>

# Time Field (/components/tanstack-form/time-field)

`TimeField` is a time-only picker built from two shadcn/ui `Select` inputs — hours `00`–`23` and minutes in 5-minute steps. It binds to a `string` in the `HH:mm` 24-hour format and reads its state from TanStack Form's field context.

#### Built-in features [#built-in-features]

* **Two-select picker**: hours and minutes as shadcn `Select` inputs — consistent styling, full keyboard support
* **Field-context binding**: reads value and validation state via `useFieldContext`
* **Range constraints**: pass `min` / `max` (as `HH:mm` strings) to disable out-of-range options
* **Validation**: surfaces TanStack Form validator errors below the picker

## Setup [#setup]

```tsx
import { createFormHook } from '@tanstack/react-form';
import { fieldContext, formContext } from '@/components/ui/shuip/tanstack-form/form-context';
import { TimeField } from '@/components/ui/shuip/tanstack-form/time-field';

const { useAppForm } = createFormHook({
  fieldContext,
  formContext,
  fieldComponents: { TimeField },
  formComponents: {},
});

<form.AppField
  name='meetingTime'
  children={(field) => <field.TimeField label='Meeting time' />}
/>
```

The value is a `string` in `HH:mm` format (or empty string when unset). Picking only the hour or only the minute defaults the other part to `00`.

## Constraining the range [#constraining-the-range]

`min` and `max` accept `HH:mm` strings; out-of-range hour and minute options are disabled:

```tsx
<field.TimeField label='Appointment' min='09:00' max='18:00' />
```

## Examples [#examples]

## Props [#props]

# Time Range (/components/tanstack-form/time-range)

`TimeRangeField` is two coupled time pickers — a start and an end — reading a single `{ start, end }` object from TanStack Form's field context. Both values are `HH:mm` strings.

#### Built-in features [#built-in-features]

* **Coupled pickers**: choosing a start time sets the end to one hour later automatically
* **`start < end` enforced**: end options at or before the start are disabled in the dropdowns
* **Single object binding**: bind the field to a `{ start, end }` value
* **Validation**: surfaces TanStack Form validator errors below the pickers

## Setup [#setup]

```tsx
import { createFormHook } from '@tanstack/react-form';
import { fieldContext, formContext } from '@/components/ui/shuip/tanstack-form/form-context';
import { TimeRangeField } from '@/components/ui/shuip/tanstack-form/time-range';

const { useAppForm } = createFormHook({
  fieldContext,
  formContext,
  fieldComponents: { TimeRangeField },
  formComponents: {},
});

// defaultValues: { slot: { start: '', end: '' } }
<form.AppField
  name='slot'
  children={(field) => <field.TimeRangeField label='Meeting slot' />}
/>
```

The value is `{ start: string; end: string }`, each a `HH:mm` string (empty when unset). Changing the start always resets the end to one hour after the new start.

## Examples [#examples]

## Props [#props]

# Query Boundary (/components/tanstack-query/query-boundary)

`QueryBoundary` is a wrapper component that combines TanStack Query's error handling with React Suspense for comprehensive query state management. It automatically catches query errors, displays loading states, and provides retry functionality.

The component eliminates the need to manually wrap components with multiple boundary providers. It handles both synchronous errors and async query failures with a unified interface and consistent error recovery patterns.

#### Built-in features [#built-in-features]

* **Automatic error catching**: Captures both sync and async query errors
* **Suspense integration**: Built-in loading state management with React Suspense
* **Error recovery**: One-click retry functionality with query reset
* **Customizable fallbacks**: Override default loading and error UI components
* **Query key tracking**: Optional debugging information for failed queries

## Basic usage [#basic-usage]

Wrap components that use TanStack Query hooks:

```tsx
import { QueryBoundary } from '@/components/ui/shuip/tanstack-query/query-boundary';

export default function App() {
  return (
    <QueryBoundary 
      queryKeys={['users']}
      loadingFallback={<div>Loading users...</div>}
    >
      <UsersList />
    </QueryBoundary>
  );
}

function UsersList() {
  const { data } = useQuery({
    queryKey: ['users'],
    queryFn: fetchUsers
  });

return <div>{data.map(user => user.name)}</div>;
}
```

## Custom error handling [#custom-error-handling]

Override the default error fallback for custom error UI:

```tsx
function CustomErrorFallback({ error, resetErrorBoundary }) {
  return (
    <div className="text-center p-8">
      <h3 className="text-lg font-semibold mb-2">Something went wrong</h3>
      <p className="text-muted-foreground mb-4">{error.message}</p>
      <button onClick={resetErrorBoundary}>
        Try again
      </button>
    </div>
  );
}

<QueryBoundary 
  queryKeys={['users', 'posts']}
  errorFallback={CustomErrorFallback}
  loadingFallback={<div>Loading...</div>}
>
  <Dashboard />
</QueryBoundary>
```

## Default error fallback [#default-error-fallback]

The built-in error fallback includes:

* Error icon and message display
* Query key debugging information
* One-click retry functionality
* Consistent styling with your design system

## Props [#props]

<TypeTable
  type="{
  children: {
    description: 'The child components to wrap in the boundary.',
    type: 'React.ReactNode',
  },
  queryKeys: {
    description: 'The query keys to monitor for debugging (optional).',
    type: 'string[]',
  },
  loadingFallback: {
    description: 'The fallback to display during loading (default: "Loading...").',
    type: 'React.ReactNode',
  },
  errorFallback: {
    description: 'The custom fallback to display on error (optional).',
    type: '(props: FallbackProps) => React.ReactNode',
  },
}"
/>

Premium Feature

John Doe