# Adaptable Forms

Canonical page: https://www.adaptabletools.com/docs/ui-tutorial-configuring-adaptable-forms

- Adaptable Forms are widely used in AdapTable and are highly configurable and flexible
- They dynamically display form data and are widely used including Export, Alerts and Data Sets
- Form **buttons** use [AdaptableButton](https://www.adaptabletools.com/docs/ui-tutorial-displaying-adaptable-buttons/index.md) — see the [Buttons guide](https://www.adaptabletools.com/docs/ui-tutorial-displaying-adaptable-buttons/index.md)

## Topics on this Page

| Topic                                          | Summary                              |
| ---------------------------------------------- | ------------------------------------ |
| [AdaptableForm object](#adaptable-form-object) | Title, fields, buttons               |
| [Field types](#field-types)                    | Controls including `custom` render   |
| [Where forms appear](#adaptable-form-object)   | Exports, alerts, row forms, toolbars |
| [Buttons on forms](#buttons)                   | Validation and onClick handlers      |

[UI Guides](https://www.adaptabletools.com/docs/ui-tutorial-overview/index.md).

There are a few places in AdapTable where a custom form can be displayed, including:

- [Custom Export Destinations](https://www.adaptabletools.com/docs/handbook-exporting-destinations-custom/index.md)
- [Alert Messages](https://www.adaptabletools.com/docs/handbook-alerting-message/index.md)
- [Data Sets](https://www.adaptabletools.com/docs/handbook-data-sets/index.md)
- [Custom Toolbars](https://www.adaptabletools.com/docs/ui-dashboard-custom-toolbars/index.md#providing-an-inline-form) - inline form controls rendered directly in a Dashboard Custom Toolbar
- [Action Column Forms](https://www.adaptabletools.com/docs/handbook-action-column-form/index.md) - a Form popover opened from an Action Column cell
- [Row Forms](https://www.adaptabletools.com/docs/handbook-row-form/index.md) - the Create / Clone / Edit Row dialogs, with per-column overrides via `rowFormField`

AdapTable provides an Adaptable Form to make displaying form data easy.

Adaptable Forms are primarily made up of 3 collections:

- Title and Description
- Form Fields
- Adaptable Buttons

## Adaptable Form Object

Adaptable Forms are defined using the [`AdaptableForm`](https://www.adaptabletools.com/docs/reference/adaptableform.md) object, defined as follows:

| Property | Type | Description | Default |
| --- | --- | --- | --- |
| [buttons](https://www.adaptabletools.com/docs/reference/adaptableform.md#buttons) | [`AdaptableButton`](https://www.adaptabletools.com/docs/reference/adaptablebutton.md)`<T>[]` | Buttons to include in the Form |   |
| [description](https://www.adaptabletools.com/docs/reference/adaptableform.md#description) | `string` | Additional information to appear in the Form |   |
| [fields](https://www.adaptabletools.com/docs/reference/adaptableform.md#fields) | `(`[`AdaptableFormField`](https://www.adaptabletools.com/docs/reference/adaptableformfield.md)` \| `[`AdaptableFormField`](https://www.adaptabletools.com/docs/reference/adaptableformfield.md)`[] \| `[`AdaptableFormFieldGroup`](https://www.adaptabletools.com/docs/reference/adaptableformfieldgroup.md)`)[]` | Collection of Dynamic Fields and Field Groups to display.<br/><br/>Items can be:<br/>- a single  (rendered on its own row in the<br/> default `rows` layout, or as one cell in the `inline` layout),<br/>- an array of  (rendered side-by-side on the<br/> same row in the `rows` layout), or<br/>- an  (a labelled section that<br/> visually groups related fields). |   |
| [layout](https://www.adaptabletools.com/docs/reference/adaptableform.md#layout) | [`AdaptableFormLayout`](https://www.adaptabletools.com/docs/reference/adaptableformlayout.md) | How the form&#39;s fields are arranged on screen.<br/><br/>- `rows` (default): each field on its own row, label on the left and<br/> input on the right. Suitable for popups / wizards.<br/>- `inline`: fields are placed side-by-side on a single horizontal line,<br/> with the label rendered immediately before its input. Designed for<br/> compact contexts such as Dashboard Custom Toolbars where vertical<br/> real-estate is scarce. | &#39;rows&#39; |
| [onSubmit](https://www.adaptabletools.com/docs/reference/adaptableform.md#onsubmit) | `(formData: TData, context: T) => void` | Optional form-level submit hook.<br/><br/>Fired when the user presses `Enter` while focus is inside any field<br/>input AND the form is currently valid. The full `formData` is passed<br/>through, typed as `TData` if you&#39;ve supplied a custom shape.<br/><br/>Use this as an ergonomic shortcut to avoid wiring an explicit &quot;Submit&quot;<br/>button - or in addition to one, so power users can press Enter to<br/>commit. If the form is invalid the hook is not invoked. |   |
| [title](https://www.adaptabletools.com/docs/reference/adaptableform.md#title) | `string` | Title to appear in the Form |   |

## Title & Description

The form object has 2 string properties used to display information about the form:

- `title` - text shown at the top of the Form
- `description` - additional text showing information the form requires and displayed beneath the title

## Fields

A Form can contain as many fields as required.

All fields are of type [`AdaptableFormField`](https://www.adaptabletools.com/docs/reference/adaptableformfield.md) which is defined as follows:

| Property | Type | Description | Default |
| --- | --- | --- | --- |
| [clearToDefault](https://www.adaptabletools.com/docs/reference/adaptableformfield.md#cleartodefault) | `boolean` | For single `select` fields only. When the user clears the combobox,<br/>whether to restore  instead of leaving the field empty.<br/><br/>Defaults to `true` when `defaultValue` is set, otherwise `false`.<br/>Set to `false` when an empty selection is a distinct state from the default. |   |
| [defaultValue](https://www.adaptabletools.com/docs/reference/adaptableformfield.md#defaultvalue) | `string \| boolean \| number \| Array<string \| number \| boolean>` | Field Default Value - can be of type string, boolean, number, or for<br/>`select` fields with `multi: true` an array of those.<br/><br/>For single `select` fields, this is also the value restored when the user<br/>clears the combobox (unless  is `false`). |   |
| [disabled](https://www.adaptabletools.com/docs/reference/adaptableformfield.md#disabled) | `boolean \| ((formData: `[`AdaptableFormData`](https://www.adaptabletools.com/docs/reference/adaptableformdata.md)`, context: `[`BaseContext`](https://www.adaptabletools.com/docs/reference/basecontext.md)`) => boolean)` | Disable the field&#39;s input. Either a boolean or a function evaluated<br/>against the current form data. Disabled fields render but the user<br/>cannot edit them. |   |
| [fieldType](https://www.adaptabletools.com/docs/reference/adaptableformfield.md#fieldtype) | [`AdaptableFormFieldType`](https://www.adaptabletools.com/docs/reference/adaptableformfieldtype.md) | Field Type - dictates which UI control is rendered |   |
| [helpText](https://www.adaptabletools.com/docs/reference/adaptableformfield.md#helptext) | `string` | Inline help text rendered immediately below the field&#39;s input. Useful<br/>for short explanations such as &quot;format: YYYY-MM-DD&quot; or &quot;min 3 chars&quot;. |   |
| [hidden](https://www.adaptabletools.com/docs/reference/adaptableformfield.md#hidden) | `boolean \| ((formData: `[`AdaptableFormData`](https://www.adaptabletools.com/docs/reference/adaptableformdata.md)`, context: `[`BaseContext`](https://www.adaptabletools.com/docs/reference/basecontext.md)`) => boolean)` | Hide the field. Either a boolean or a function evaluated against the<br/>current form data. Hidden fields are not rendered and are excluded from<br/>validation. |   |
| [label](https://www.adaptabletools.com/docs/reference/adaptableformfield.md#label) | `string` | Label to display in the Field |   |
| [max](https://www.adaptabletools.com/docs/reference/adaptableformfield.md#max) | `number \| string` | Maximum allowed value. For `number` and `slider`: the highest accepted<br/>number. For `date`, `time` and `datetime`: the latest allowed value in<br/>ISO format. |   |
| [maxLength](https://www.adaptabletools.com/docs/reference/adaptableformfield.md#maxlength) | `number` | Maximum length for `text` and `textarea` fields. |   |
| [min](https://www.adaptabletools.com/docs/reference/adaptableformfield.md#min) | `number \| string` | Minimum allowed value. For `number` and `slider`: the lowest accepted<br/>number. For `date`, `time` and `datetime`: the earliest allowed value<br/>in ISO format (`YYYY-MM-DD` / `HH:mm` / `YYYY-MM-DDTHH:mm`). |   |
| [minLength](https://www.adaptabletools.com/docs/reference/adaptableformfield.md#minlength) | `number` | Minimum length for `text` and `textarea` fields. |   |
| [multi](https://www.adaptabletools.com/docs/reference/adaptableformfield.md#multi) | `boolean` | For `select` fields only. When `true` the field renders as a<br/>multi-select combobox; the field&#39;s value is an array of selected<br/>`option.value`s rather than a single value. | false |
| [name](https://www.adaptabletools.com/docs/reference/adaptableformfield.md#name) | `string` | Name of the Field |   |
| [onValueChange](https://www.adaptabletools.com/docs/reference/adaptableformfield.md#onvaluechange) | `(value: any, context: `[`BaseContext`](https://www.adaptabletools.com/docs/reference/basecontext.md)`) => void` | Optional callback invoked whenever value of this field changes |   |
| [options](https://www.adaptabletools.com/docs/reference/adaptableformfield.md#options) | [`AdaptableFormFieldOption`](https://www.adaptabletools.com/docs/reference/adaptableformfieldoption.md)`[] \| ((formData: `[`AdaptableFormData`](https://www.adaptabletools.com/docs/reference/adaptableformdata.md)`, context: `[`BaseContext`](https://www.adaptabletools.com/docs/reference/basecontext.md)`) => `[`AdaptableFormFieldOption`](https://www.adaptabletools.com/docs/reference/adaptableformfieldoption.md)`[] \| Promise<`[`AdaptableFormFieldOption`](https://www.adaptabletools.com/docs/reference/adaptableformfieldoption.md)`[]>)` | Items to populate the `select` and `radio` fieldTypes.<br/><br/>Either a static array, or a function that derives the options from the<br/>current form data and Adaptable context. The function form may return<br/>a Promise for asynchronously-loaded options - the form will render the<br/>field with no items until the promise resolves. |   |
| [pattern](https://www.adaptabletools.com/docs/reference/adaptableformfield.md#pattern) | `string` | Regular expression that the value of a `text` field must match. |   |
| [placeholder](https://www.adaptabletools.com/docs/reference/adaptableformfield.md#placeholder) | `string` | Placeholder text shown inside `text`, `textarea`, `number`, `date`,<br/>`time` and `datetime` inputs when empty. For `select` fields it is<br/>rendered as the empty-state label when no value is selected.<br/><br/>When omitted on a `select` field with a , the label of<br/>the matching `options` entry is used as the empty-state label. |   |
| [render](https://www.adaptabletools.com/docs/reference/adaptableformfield.md#render) | `(params: `[`AdaptableFormFieldRenderParams`](https://www.adaptabletools.com/docs/reference/adaptableformfieldrenderparams.md)`) => React.ReactNode` | For `custom` fields only. Renders an arbitrary React node as the<br/>field&#39;s input. Receives the current value, a `setValue` setter<br/>(controlled), the current form data, the Adaptable context and the<br/>resolved `disabled` state.<br/><br/>Use this as an escape hatch when none of the built-in `fieldType`s<br/>fit - e.g. to render a star-rating widget, a tag editor or any<br/>bespoke control. |   |
| [required](https://www.adaptabletools.com/docs/reference/adaptableformfield.md#required) | `boolean` | If `true` the field is treated as required. An empty value (`''`,<br/>`null`, `undefined`, or unchecked checkbox) will produce a validation<br/>error. |   |
| [rows](https://www.adaptabletools.com/docs/reference/adaptableformfield.md#rows) | `number` | For `textarea` fields: the visible number of text rows. | 3 |
| [step](https://www.adaptabletools.com/docs/reference/adaptableformfield.md#step) | `number` | Stepping interval for `number`, `slider`, `time` and `datetime`<br/>fields. |   |
| [tooltip](https://www.adaptabletools.com/docs/reference/adaptableformfield.md#tooltip) | `string` | Tooltip shown when hovering the field&#39;s label. |   |
| [validate](https://www.adaptabletools.com/docs/reference/adaptableformfield.md#validate) | `(value: any, formData: `[`AdaptableFormData`](https://www.adaptabletools.com/docs/reference/adaptableformdata.md)`, context: `[`BaseContext`](https://www.adaptabletools.com/docs/reference/basecontext.md)`) => string \| null \| undefined` | Custom field-level validation. Return an error message string to mark<br/>the field invalid, or `null`/`undefined` if the value is valid.<br/><br/>Custom validation runs *after* built-in checks (`required`, `min`,<br/>`max`, `pattern`, etc.) - the first failing check wins. |   |

### Field Types

The `fieldType` property describes which UI control to display for the field.

It is of type [`AdaptableFormFieldType`](https://www.adaptabletools.com/docs/reference/adaptableformfieldtype.md) and can be any of:

| `fieldType`  | UI control                                                                                                                                         |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text`       | Single-line text input                                                                                                                             |
| `textarea`   | Multi-line text input - configurable `rows` (defaults to 3)                                                                                        |
| `number`     | Numeric input                                                                                                                                      |
| `slider`     | Range slider with min/max/step plus an inline value read-out - see [Slider](#slider)                                                               |
| `date`       | Native HTML5 date picker                                                                                                                           |
| `time`       | Time-of-day picker (`HH:mm`)                                                                                                                       |
| `datetime`   | Combined date + time picker                                                                                                                        |
| `color`      | Native HTML5 colour picker (value is a `#RRGGBB` string)                                                                                           |
| `select`     | Combobox populated from `options` (single or multi - see [Multi-Select](#multi-select))                                                            |
| `radio`      | Mutually-exclusive group of radio buttons populated from `options` - see [Radio Group](#radio-group)                                               |
| `checkbox`   | Checkbox                                                                                                                                           |
| `textOutput` | Read-only inline label - displays the field's current value as plain text (useful for static guidance or computed labels alongside other controls) |
| `custom`     | Renders any controlled React node via a `render` function - see [Custom Fields](#custom-fields)                                                    |

If the field type is 'select' or 'radio', the `options` property can be used to populate what appears in the dropdown / radio group

#### Textarea

A `textarea` field renders a multi-line text input. The `rows` property controls the visible height (default `3`); `minLength` and `maxLength` are honoured for validation.

```ts
{
  name: 'notes',
  label: 'Notes',
  fieldType: 'textarea',
  rows: 5,
  maxLength: 500,
  placeholder: 'Internal notes...',
}
```

Pressing `Enter` inside a `textarea` inserts a newline rather than submitting the form, even when `onSubmit` is set. Use `Shift + Enter` if you want both behaviours alongside.

#### Slider

A `slider` field renders a range input with `min` / `max` / `step` plus a tabular value read-out next to it. The current value is always a number.

```ts
{
  name: 'opacity',
  label: 'Opacity',
  fieldType: 'slider',
  defaultValue: 0.5,
  min: 0,
  max: 1,
  step: 0.05,
}
```

#### Radio Group

A `radio` field renders all `options` as a row of mutually-exclusive radio buttons. Use it instead of a `select` when there are only a handful of options and you want them all visible at once.

```ts
{
  name: 'priority',
  label: 'Priority',
  fieldType: 'radio',
  defaultValue: 'normal',
  options: [
    { label: 'Low',    value: 'low'    },
    { label: 'Normal', value: 'normal' },
    { label: 'High',   value: 'high'   },
  ],
}
```

#### Time, Datetime & Colour

The `time`, `datetime` and `color` field types wrap the corresponding native HTML5 inputs:

- `time` - the value is an `HH:mm` (or `HH:mm:ss` when `step` is sub-minute) string
- `datetime` - combined date + time, value is `YYYY-MM-DDTHH:mm`
- `color` - HTML5 colour picker, value is a `#RRGGBB` string

```ts
{ name: 'reminderAt', label: 'Reminder', fieldType: 'time' },
{ name: 'startsAt',   label: 'Starts',   fieldType: 'datetime' },
{ name: 'tagColour',  label: 'Tag',      fieldType: 'color', defaultValue: '#1e88e5' },
```

#### Multi-Select

A `select` field can render as a multi-select by setting `multi: true`. The field's value becomes an array of selected `option.value`s rather than a single value:

```ts
{
  name: 'languages',
  label: 'Languages',
  fieldType: 'select',
  multi: true,
  defaultValue: [],
  options: [
    { label: 'JavaScript', value: 'JavaScript' },
    { label: 'TypeScript', value: 'TypeScript' },
    { label: 'Python',     value: 'Python'     },
  ],
}
```

For multi-selects the `required` validation requires at least one selected option, and an empty array (`[]`) - not an empty string - is treated as the empty state

#### Read-only output (`textOutput`)

A `textOutput` field is read-only: it echoes `formData[field.name]` as plain text with no input control. It never participates in validation (even if `required` were set, it would be ignored). Use it for static guidance, computed summaries, or labels that sit next to editable fields—often combined with [multiple fields on one row](#multiple-fields-on-one-row).

```ts
{
  name: 'summaryLine',
  label: 'Summary',
  fieldType: 'textOutput',
},
// elsewhere in your host code, keep `formData.summaryLine` in sync
```

#### Dynamic Options

In addition to a static array, the `options` of a `select` field can be a function which receives `(formData, context)` and returns the option list. This is invaluable when the choices depend on another field, or live in Adaptable's API.

```ts
{
  name: 'license',
  label: 'License',
  fieldType: 'select',
  options: (formData, context) => {
    if (formData.languages?.includes('Rust')) {
      return [{ label: 'MIT/Apache (Rust)', value: 'mit-apache' }];
    }
    return [
      { label: 'MIT',        value: 'mit'        },
      { label: 'Apache-2.0', value: 'apache-2.0' },
    ];
  },
}
```

The function may also return a `Promise` for asynchronously-loaded options. The form renders the field with no items until the promise resolves and then re-renders.

### Custom Fields

When none of the built-in field types fit your needs, set `fieldType: 'custom'` and supply a `render` function. The function receives the field's controlled `value`, a `setValue` setter, the entire `formData`, the Adaptable `context`, the resolved `disabled` flag, and (when invalid) the current validation message as `error` - and returns any React node.

```ts
{
  name: 'minStars',
  label: 'Min Stars',
  fieldType: 'custom',
  defaultValue: 0,
  render: ({ value, setValue, disabled, error }) => (
    <>
      <input
        type="range"
        min={0}
        max={200000}
        step={5000}
        value={Number(value) || 0}
        disabled={disabled}
        onChange={(e) => setValue(Number(e.target.value))}
      />
      {error ? <span>{error}</span> : null}
    </>
  ),
}
```

- `setValue` routes through the form's normal change pipeline, so per-field `onValueChange`, validation and `formIsValid` all keep working
- `error` is the same message the built-in fields show under the control; use it if you want bespoke error placement inside your custom control
- A custom field can also be purely read-only - a `render` function that ignores `value` and `setValue` and just renders something computed from `formData` is fine

### Field-Level Helpers

Each field can declare a few presentational helpers that surface additional information in-place:

| Property      | Effect                                                                                                     |
| ------------- | ---------------------------------------------------------------------------------------------------------- |
| `placeholder` | Empty-state text shown inside `text`, `textarea`, `number`, `date`, `time`, `datetime` and `select` inputs |
| `helpText`    | Inline hint rendered immediately below the input (e.g. "format: YYYY-MM-DD")                               |
| `tooltip`     | Hover tooltip on the field's label                                                                         |

```ts
{
  name: 'apiKey',
  label: 'API Key',
  fieldType: 'text',
  placeholder: 'sk-...',
  helpText: 'Find your key under Settings → Tokens',
  tooltip: 'Used for authenticated requests',
}
```

### Hidden & Disabled Fields

Field visibility and edit-state can be data-driven. Both `hidden` and `disabled` accept either a static boolean or a function that receives `(formData, context)` so they can react to other fields' values:

```ts
{
  name: 'minWatchers',
  label: 'Min Watchers',
  fieldType: 'number',
  hidden: (formData) => !formData.onlyHasWiki,   // appear only when checkbox is on
}
{
  name: 'reason',
  label: 'Reason',
  fieldType: 'text',
  disabled: (formData) => formData.action === 'delete',
}
```

Hidden fields are excluded from validation as well as from the rendered DOM, so a `required` field that's currently hidden will not block form submission

### Validation

A field can declare validation rules and the form will surface inline errors and an aggregate `formIsValid` flag that buttons can gate on.

| Property                         | Applies to                                     | Effect                                                                             |
| -------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------- |
| `required`                       | all editable                                   | Empty value (`''`, `null`, `undefined`, unchecked) is invalid                      |
| `min` / `max`                    | `number`, `slider`, `date`, `time`, `datetime` | Numeric or date/time range bounds                                                  |
| `step`                           | `number`, `slider`, `time`, `datetime`         | Stepping interval                                                                  |
| `minLength` / `maxLength`        | `text`, `textarea`                             | Character-count bounds                                                             |
| `pattern`                        | `text`                                         | Regular expression that the value must match                                       |
| `validate(value, formData, ctx)` | all editable                                   | Custom validator returning an error message string, or `null`/`undefined` if valid |

```ts
{
  name: 'email',
  label: 'Email',
  fieldType: 'text',
  required: true,
  pattern: '^\\S+@\\S+\\.\\S+$',
  helpText: 'we will only use this for delivery',
  validate: (value, formData) => {
    if (formData.notifyByEmail && !value) {
      return 'Email is required when notifications are on';
    }
    return null;
  },
}
```

For each field, checks run in this order; the **first failure** produces the error message and later checks are skipped:

1. `required` (empty / unchecked / empty multi-select)
2. Built-in rules when a value is present: `min` / `max` for `number` and `slider`; `min` / `max` for `date`, `time` and `datetime`; `minLength` / `maxLength` for `text` and `textarea`; `pattern` for `text` (see table above for which properties apply to which types). The `step` property affects native inputs but is **not** part of this validation pass.
3. Custom `validate(value, formData, context)`

`textOutput` fields skip validation entirely.

Per-field errors render below the input (unless you handle them yourself in a `custom` field via `error`). The form also produces an aggregate `formIsValid: boolean` (and a `formErrors: Record<string, string>` map) which any button declared on the form can read from its `context` to gate `disabled` or `onClick` - e.g. a Submit button that stays disabled until every field is valid.

### Reacting to Field Changes

Each Form Field can declare an `onValueChange` callback that fires only when **that specific field** changes.

This is designed for ergonomic, control-level reactions.

For instance you can use it to filter the grid as soon as a select changes) without having to inspect the whole form's data via the form-level change callback.

- This is particularly useful for "live" forms where each control should act immediately on change
- e.g. a Custom Toolbar select that filters the grid as soon as the user picks an option, with no Apply button required

```ts
{
  name: 'language',
  label: 'Language',
  fieldType: 'select',
  options: [...],
  onValueChange: (value, context) => {
    // `value` is the new value of just this field
    // `context.formData` always reflects the latest values (`formData`), including the field that just changed
    // this ensures that consumers always see up-to-date values; no extra plumbing needed
  },
},
```

Pair this with the host's form-level change callback (e.g. `onToolbarFormChange` for Custom Toolbars) when several fields combine to drive a single action

### Form Layout

The form's `layout` property controls how fields are arranged on screen:

- `'rows'` (default) - each field on its own row, label on the left and input on the right; suitable for popups, wizards and full-size forms (Alerts, Export, Data Sets)
- `'inline'` - all fields are placed side-by-side on a single horizontal line, with the label rendered immediately before its input; designed for compact contexts such as Dashboard [Custom Toolbars](https://www.adaptabletools.com/docs/ui-dashboard-custom-toolbars/index.md#providing-an-inline-form) where vertical space is at a premium

Custom Toolbars apply `layout: 'inline'` automatically - you don't need to set it manually when using `toolbarForm`

### Multiple fields on one row

In the default `rows` layout, each entry in `fields` is normally a single [`AdaptableFormField`](https://www.adaptabletools.com/docs/reference/adaptableformfield.md) or a [`AdaptableFormFieldGroup`](https://www.adaptabletools.com/docs/reference/adaptableformfieldgroup.md). You can also supply an **array of fields** as an entry: every field in that array shares one grid row, with each label/control pair laid out side-by-side. The same array shorthand works inside a group's `fields` array.

```ts
fields: [
  [
    { name: 'firstName', label: 'First', fieldType: 'text', required: true },
    { name: 'lastName',  label: 'Last',  fieldType: 'text', required: true },
  ],
  { name: 'email', label: 'Email', fieldType: 'text' },
],
```

If every field in an array row is [hidden](#hidden--disabled-fields), the whole row is omitted.

### Field Groups

Long forms can be split into logical sections by interleaving [`AdaptableFormFieldGroup`](https://www.adaptabletools.com/docs/reference/adaptableformfieldgroup.md) entries with regular fields. A group has an optional `title` and `description` and contains its own `fields` array; visually it renders as a labelled section with a divider.

```ts
fields: [
  { name: 'name',  label: 'Name',  fieldType: 'text', required: true },
  {
    kind: 'group',
    title: 'Notification Preferences',
    description: 'How would you like us to reach you?',
    fields: [
      { name: 'notifyByEmail', label: 'Email', fieldType: 'checkbox' },
      { name: 'notifyBySMS',   label: 'SMS',   fieldType: 'checkbox' },
    ],
  },
  {
    kind: 'group',
    title: 'Advanced',
    hidden: (formData) => !formData.notifyByEmail,
    fields: [
      { name: 'replyTo', label: 'Reply-To', fieldType: 'text', placeholder: 'no-reply@…' },
    ],
  },
],
```

Groups also accept a `hidden` flag (boolean or function) that lets you collapse an entire section in or out based on form data. A hidden group's fields are excluded from validation just like individual hidden fields.

In the `inline` layout (e.g. Custom Toolbars) the group's title and description are not rendered - the layout is too compact for sectioning - but the child fields still flow inline alongside the rest.

### Form-Level Submit

Set [`AdaptableForm`](https://www.adaptabletools.com/docs/reference/adaptableform.md)'s `onSubmit` callback to react when the user presses `Enter` inside any field input (and the form is valid). This is an ergonomic shortcut that complements - or replaces - an explicit Submit button.

```ts
{
  fields: [...],
  onSubmit: (formData, context) => {
    context.adaptableApi.alertApi.showAlert({ Header: 'Submitted', Message: '…' });
  },
}
```

- Pressing `Enter` inside a `textarea` inserts a newline rather than submitting (use `Shift + Enter` if you want to override) - this matches user expectations for multi-line input
- The hook is **not** invoked when the form is invalid, so you don't need to re-validate inside the callback
- The first argument is fully typed when you supply a custom `TData` shape (see [Strongly-Typed Form Data](#strongly-typed-form-data))

### Strongly-Typed Form Data

By default `formData` is loosely typed as `Record<string, any>`. When you care about correctness you can declare the shape of your form's data and pass it as the second generic parameter to [`AdaptableForm`](https://www.adaptabletools.com/docs/reference/adaptableform.md):

```ts
type MyFormData = {
  name: string;
  age: number;
  notifyByEmail: boolean;
};

const formDef: AdaptableForm<MyFormContext, MyFormData> = {
  fields: [...],
  onSubmit: (formData, context) => {
    // `formData.name` is typed as string, `formData.age` as number, etc.
  },
};
```

Inside Custom Toolbars the same `TData` parameter flows through the host so `context.formData`, `onToolbarFormChange` and form-level `onSubmit` all see the strongly-typed shape:

```ts
const customToolbar: CustomToolbar<MyFormData> = {
  name: 'MyToolbar',
  toolbarForm: {
    /* ... */
  },
  onToolbarFormChange: formData => {
    // formData is MyFormData
  },
};
```

### Resetting Form Data Programmatically

When a form is hosted inside a Custom Toolbar AdapTable owns its data, so a "Clear" button (or any other handler) can roll it back to the declared `defaultValue`s without re-mounting the toolbar:

```ts
adaptableApi.dashboardApi.resetCustomToolbarFormData('MyToolbar');
// or - reset every Custom Toolbar that hosts a `toolbarForm`
adaptableApi.dashboardApi.resetCustomToolbarFormData();
```

The reset fires the toolbar's `onToolbarFormChange` callback once with the freshly-defaulted data, so any external state derived from the form (e.g. a Grid Filter expression) can rebuild itself just like it does when the user types.

For Alerts, Export and other hosts that own their own form-data lifecycle, simply re-render with a fresh `getDefaultAdaptableFormData(formDef)` value.

### Programmatic helpers

These functions are exported from `@adaptabletools/adaptable` alongside the form types:

- **`getDefaultAdaptableFormData(formDef)`** - builds initial `formData` from each field's `defaultValue` (multi-selects normalise to an array)
- **`flattenAdaptableFormFields(formDef)`** - walks `fields`, expanding groups and inline field arrays into a single flat list of [`AdaptableFormField`](https://www.adaptabletools.com/docs/reference/adaptableformfield.md) objects; useful for lookups, metadata, or custom logic that does not want to recurse the tree
- **`validateAdaptableForm(formDef, formData, context)`** - returns an [`AdaptableFormErrors`](https://www.adaptabletools.com/docs/reference/adaptableformerrors.md) map using the same rules and hidden-field skipping as the live form (see [Validation](#validation)); use when you host form data outside `AdaptableFormComponent` but want identical behaviour
- **`isAdaptableFormFieldGroup(entry)`** - type guard for `kind: 'group'` entries when walking `fields` yourself

```ts
import {
  flattenAdaptableFormFields,
  getDefaultAdaptableFormData,
  validateAdaptableForm,
} from '@adaptabletools/adaptable';

const data = getDefaultAdaptableFormData(formDef);
const errors = validateAdaptableForm(formDef, data, context);
const names = flattenAdaptableFormFields(formDef).map(f => f.name);
```

### Accessibility

`AdaptableFormComponent` is wired up to be screen-reader friendly out of the box:

- Each field's `<label>` is programmatically associated with its input via `htmlFor` / `id`, so clicking the label focuses the control and screen readers announce the label when the control is focused
- `required` fields receive `aria-required="true"`; the visible `*` marker is `aria-hidden` to avoid double-announcement
- Fields with a current validation error get `aria-invalid="true"` and an `aria-describedby` reference to the error element, which itself has `role="alert"` so the message is announced live
- `helpText` is also linked via `aria-describedby` so it reads alongside the input
- `radio` fields render as a `role="radiogroup"` with `aria-labelledby` pointing at the label
- `select` fields wrap the underlying combobox in a labelled `role="group"` so the relationship to the field's label is preserved through the popup

You don't need to do anything special - just supply meaningful `label`s and (where relevant) `helpText` / `tooltip` strings.

## Buttons

Forms can additionally include Buttons to perform actions.

The Buttons are of type [`AdaptableButton`](https://www.adaptabletools.com/docs/reference/adaptablebutton.md) described above.

When a form is rendered through `AdaptableFormComponent`, each button's handlers receive a `context` object that includes the usual Adaptable APIs **plus** the current form snapshot:

- `context.formData` - latest values (same shape as `onSubmit`'s first argument)
- `context.formIsValid` - `true` when no field has a validation error
- `context.formErrors` - map of field `name` to error message (absent keys mean valid)

Use these to disable a Submit button until the form is valid, branch `onClick` on validity, or read errors without re-running validation yourself:

```ts
buttons: [
  {
    label: 'Submit',
    tone: 'success',
    disabled: (_button, ctx) => !ctx.formIsValid,
    onClick: (_button, ctx) => {
      if (!ctx.formIsValid) return;
      // commit ctx.formData
    },
  },
],
```

See the [Adaptable Buttons](https://www.adaptabletools.com/docs/ui-tutorial-displaying-adaptable-buttons/index.md) guide for button properties and contexts.

### FAQ

**Form vs Row Form?**
This guide covers the **`AdaptableForm`** object. [Row Forms](https://www.adaptabletools.com/docs/handbook-row-form/index.md) use the same field model with column-aware defaults.

**Where are options for colour fields?**
Colour picker behaviour is global — [Configuring the Colour Picker](https://www.adaptabletools.com/docs/ui-tutorial-custom-colour-palette/index.md).
