# Forms and controls

Source: /tuil/docs/reference/components/forms
Locale: en

Connect semantic terminal controls to typed form state, validation, descriptions, errors, hints, and submission.





## Overview [#overview]

Connect semantic terminal controls to typed form state, validation, descriptions, errors, hints, and submission.

## Installation [#installation]

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx @mwillbanks/tuil add field text-input text-area number-input checkbox switch radio-group select multi-select autocomplete password-input search-input command-line code-editor inline-editor editable-table-cell editable-tree-node form-field-editor date-time-input
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx @mwillbanks/tuil add field text-input text-area number-input checkbox switch radio-group select multi-select autocomplete password-input search-input command-line code-editor inline-editor editable-table-cell editable-tree-node form-field-editor date-time-input
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx @mwillbanks/tuil add field text-input text-area number-input checkbox switch radio-group select multi-select autocomplete password-input search-input command-line code-editor inline-editor editable-table-cell editable-tree-node form-field-editor date-time-input
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun x @mwillbanks/tuil add field text-input text-area number-input checkbox switch radio-group select multi-select autocomplete password-input search-input command-line code-editor inline-editor editable-table-cell editable-tree-node form-field-editor date-time-input
    ```
  </CodeBlockTab>
</CodeBlockTabs>

The CLI writes source-owned components beneath the destination configured in
`tuil.config.ts`; the default import below assumes `src/components/tuil`.

<PublishedStory storyId="component-acceptance" variant="Field" />

## Components and subcomponents [#components-and-subcomponents]

| API                                                                         | Signature                    | Description                        |
| --------------------------------------------------------------------------- | ---------------------------- | ---------------------------------- |
| [`Form`](/tuil/docs/reference/components/forms/form)                             | `function Form`              | Public function Form.              |
| [`ValidationSummary`](/tuil/docs/reference/components/forms/validation-summary)  | `function ValidationSummary` | Public function ValidationSummary. |
| [`Field`](/tuil/docs/reference/components/forms/field)                           | `function Field`             | Public function Field.             |
| [`FieldLabel`](/tuil/docs/reference/components/forms/field-label)                | `constant FieldLabel`        | Public constant FieldLabel.        |
| [`FieldDescription`](/tuil/docs/reference/components/forms/field-description)    | `constant FieldDescription`  | Public constant FieldDescription.  |
| [`FieldError`](/tuil/docs/reference/components/forms/field-error)                | `constant FieldError`        | Public constant FieldError.        |
| [`FieldHint`](/tuil/docs/reference/components/forms/field-hint)                  | `constant FieldHint`         | Public constant FieldHint.         |
| [`FieldGroup`](/tuil/docs/reference/components/forms/field-group)                | `constant FieldGroup`        | Public constant FieldGroup.        |
| [`FieldSet`](/tuil/docs/reference/components/forms/field-set)                    | `constant FieldSet`          | Public constant FieldSet.          |
| [`TextInput`](/tuil/docs/reference/components/forms/text-input)                  | `function TextInput`         | Public function TextInput.         |
| [`TextArea`](/tuil/docs/reference/components/forms/text-area)                    | `function TextArea`          | Public function TextArea.          |
| [`NumberInput`](/tuil/docs/reference/components/forms/number-input)              | `function NumberInput`       | Public function NumberInput.       |
| [`Checkbox`](/tuil/docs/reference/components/forms/checkbox)                     | `function Checkbox`          | Public function Checkbox.          |
| [`Switch`](/tuil/docs/reference/components/forms/switch)                         | `function Switch`            | Public function Switch.            |
| [`RadioGroup`](/tuil/docs/reference/components/forms/radio-group)                | `function RadioGroup`        | Public function RadioGroup.        |
| [`Select`](/tuil/docs/reference/components/forms/select)                         | `function Select`            | Public function Select.            |
| [`MultiSelect`](/tuil/docs/reference/components/forms/multi-select)              | `function MultiSelect`       | Public function MultiSelect.       |
| [`Autocomplete`](/tuil/docs/reference/components/forms/autocomplete)             | `function Autocomplete`      | Public function Autocomplete.      |
| [`PasswordInput`](/tuil/docs/reference/components/forms/password-input)          | `function PasswordInput`     | Public function PasswordInput.     |
| [`SearchInput`](/tuil/docs/reference/components/forms/search-input)              | `function SearchInput`       | Public function SearchInput.       |
| [`CommandLine`](/tuil/docs/reference/components/forms/command-line)              | `function CommandLine`       | Public function CommandLine.       |
| [`CodeEditor`](/tuil/docs/reference/components/forms/code-editor)                | `function CodeEditor`        | Public function CodeEditor.        |
| [`InlineEditor`](/tuil/docs/reference/components/forms/inline-editor)            | `constant InlineEditor`      | Public constant InlineEditor.      |
| [`EditableTableCell`](/tuil/docs/reference/components/forms/editable-table-cell) | `constant EditableTableCell` | Public constant EditableTableCell. |
| [`EditableTreeNode`](/tuil/docs/reference/components/forms/editable-tree-node)   | `constant EditableTreeNode`  | Public constant EditableTreeNode.  |
| [`FormFieldEditor`](/tuil/docs/reference/components/forms/form-field-editor)     | `constant FormFieldEditor`   | Public constant FormFieldEditor.   |
| [`DateTimeInput`](/tuil/docs/reference/components/forms/date-time-input)         | `function DateTimeInput`     | Public function DateTimeInput.     |

## Interaction [#interaction]

Text controls edit directly; choice controls use arrows and Space or Enter; `Form` coordinates validation and submission.

## API and events [#api-and-events]

Controls expose `onValueChange`, `onSubmit`, focus, selection, and validation callbacks.

Every interactive component publishes semantic roles, labels, state, and focus
identity through the renderer's `SemanticRegistry`. Callback failures flow to
the owning application's error boundary.

<Mermaid
  chart="flowchart LR
  S0[&#x22;props and runtime state&#x22;]
  S1[&#x22;semantic registration&#x22;]
  S2[&#x22;focus and input routing&#x22;]
  S3[&#x22;callback or state update&#x22;]
  S4[&#x22;rerender&#x22;]
  S0 --> S1
  S1 --> S2
  S2 --> S3
  S3 --> S4"
/>

## Example [#example]

```tsx
import type { ComponentProps } from "react";
import { Form } from "@/components/tuil/forms/controls";

export function Example(props: ComponentProps<typeof Form>) {
  return <Form {...props} />;
}
```

Registry-installed components are source-owned: customize the generated file in
your application, and use the package reference for the shared runtime contracts.