npm package: @hatchd/sanity-plugin-form-builder
Description: A form builder plugin for Sanity Studio
Author: Hatchd
Latest version: 1.3.0

# Form Builder - A form builder plugin for Sanity

Create and manage forms in Sanity Studio while remaining frontend-agnostic. Use GROQ to query your forms and render them on the frontend with your preferred framework and UI kit.

This is a **Sanity Studio v3/v4** plugin.

## Supported Fields

- Text, Email, Telephone, Number, URL, Hidden, Date, Time
- Textarea
- Select (dropdown)
- Checkbox
- Checkbox group
- Radio button group
- Form group (a labelled container for grouping fields)

Each field includes a label, optional hint/error messages, and a required toggle. Select, checkbox group, and radio button group support default values and enforce unique option values.

## Installation

```sh
npm install @hatchd/sanity-plugin-form-builder
```

or

```sh
yarn add @hatchd/sanity-plugin-form-builder
```

## Usage

Add it as a plugin in `sanity.config.ts` (or .js):

```ts
import {defineConfig} from 'sanity'
import {FormBuilderPlugin} from '@hatchd/sanity-plugin-form-builder'

export default defineConfig({
  //...
  plugins: [FormBuilderPlugin({})],
})
```

This registers all form schema types. You can then create `baseForm` documents in the Studio and reference them from your page content using the `formModule` object type.

## Plugin Options

Customise which schemas are registered and override individual field schemas:

```ts
FormBuilderPlugin({
  // Override specific field schemas by logical name
  override: {
    input: {
      disableFields: ['fieldPlaceholder'],
      addFields: [
        /* additional Sanity field definitions */
      ],
    },
    textarea: {
      /* ... */
    },
    // Also: select, checkbox, checkboxGroup, radioButtonGroup
  },

  // Include only specific schemas (allowlist)
  schemas: ['formDocument', 'formFieldType', 'formTextareaType'],

  // Or exclude specific schemas (denylist)
  disableSchemas: ['checkboxGroup', 'radioButtonGroup'],
})
```

`schemas` and `disableSchemas` are mutually exclusive — if `schemas` is provided, only those are registered. If `disableSchemas` is provided, everything except those is registered.

### Logical Names for `disableSchemas`

| Logical Name       | Schema Type            |
| ------------------ | ---------------------- |
| `input`            | `formFieldType`        |
| `textarea`         | `formTextareaType`     |
| `select`           | `formSelectType`       |
| `checkbox`         | `formCheckboxType`     |
| `checkboxGroup`    | `formCheckboxGroup`    |
| `radioButtonGroup` | `formRadioButtonGroup` |

## Schema

### `baseForm` (Document)

The main form definition document.

```ts
{
  formTitle: string        // Required
  description?: string
  emailTo: string[]        // Array of email addresses (validated)
  emailSubject?: string
  customFormFields: array  // The form fields added by the editor
}
```

### `formEntry` (Document)

Read-only submission capture. Created by your frontend when a form is submitted.

```ts
{
  formTitle?: string
  formRef?: Reference      // Reference to the baseForm
  fields?: Array<{
    label?: string
    value?: string
  }>
}
```

## TypeScript Support

All form types are exported for use in your frontend:

```ts
import type {
  BaseForm,
  FormEntry,
  FormCustomField,
  FormField,
  FormTextarea,
  FormSelect,
  FormCheckbox,
  FormCheckboxGroup,
  FormRadioButtonGroup,
  FormGroup,
  FormModule,
} from '@hatchd/sanity-plugin-form-builder'
```

The plugin also exports `FormBuilderEnums` for referencing document and field type names without a Zod dependency:

```ts
import {FormBuilderEnums} from '@hatchd/sanity-plugin-form-builder'

FormBuilderEnums.documents.baseForm // 'baseForm'
FormBuilderEnums.fields.formField // 'formField'
```

## License

[MIT](LICENSE) © [Hatchd Team](https://hatchd.com.au)