# Form Controls

Form controls are the individual input components that compose a form. They render the standard interactive inputs — text, selection, toggles, sliders, pickers, file uploads — and integrate with a parent `form`/`data-form` for submission. Each control accepts the shared `props` bag plus `visibility`, `responsive`, and `i18n` modules. Most controls share a common set of attributes (`name`, `label`, `placeholder`, `disabled`, `required`, `defaultValue`).

```yaml
components:
  - type: form
    action: { type: crud, operation: create }
    children:
      - { type: input, name: email, props: { type: email, placeholder: 'you@example.com' } }
      - {
          type: select,
          name: plan,
          options: [{ label: Free, value: free }, { label: Pro, value: pro }],
        }
      - { type: switch, name: subscribe, props: { checked: true } }
```

## `input`

A single-line text input.

| Property             | Description                                                                     |
| -------------------- | ------------------------------------------------------------------------------- |
| `name`               | Field name (key in the submitted payload).                                      |
| `props.type`         | HTML input type: `text`, `email`, `password`, `number`, `tel`, `url`, `search`. |
| `props.placeholder`  | Placeholder text.                                                               |
| `props.defaultValue` | Initial value.                                                                  |
| `props.disabled`     | Disable the input.                                                              |
| `props.required`     | Mark the field required.                                                        |

## `textarea`

A multi-line text input.

| Property            | Description                                                |
| ------------------- | ---------------------------------------------------------- |
| `name`              | Field name.                                                |
| `props.rows`        | Visible number of text lines.                              |
| `props.maxLength`   | Maximum character count (prevents input beyond the limit). |
| `props.autoResize`  | Set `true` to expand the height as content grows.          |
| `props.placeholder` | Placeholder text.                                          |

## `select`

A dropdown that shows the selected value and opens an options list on click.

| Property             | Description                                                            |
| -------------------- | ---------------------------------------------------------------------- |
| `name`               | Field name.                                                            |
| `options`            | Array of `{ label, value, disabled?, icon? }` (at least one required). |
| `props.placeholder`  | Text shown when no value is selected.                                  |
| `props.searchable`   | Set `true` to enable type-ahead filtering of options.                  |
| `props.defaultValue` | Pre-selected value.                                                    |

## `combobox`

A searchable, autocompleting select for large option sets.

| Property             | Description                                                        |
| -------------------- | ------------------------------------------------------------------ |
| `name`               | Field name.                                                        |
| `options`            | Array of `{ label, value }` options (filtered by the typed query). |
| `props.placeholder`  | Placeholder for the search field.                                  |
| `props.defaultValue` | Pre-selected value.                                                |

## `checkbox`

A single checkbox input.

| Property              | Description                                 |
| --------------------- | ------------------------------------------- |
| `name`                | Field name.                                 |
| `props.checked`       | Render in the checked state.                |
| `props.indeterminate` | Render with a dash indicator (mixed state). |
| `props.disabled`      | Disable toggling.                           |

## `radio-group`

A group of mutually exclusive radio options.

| Property             | Description                                     |
| -------------------- | ----------------------------------------------- |
| `name`               | Field name.                                     |
| `options`            | Array of `{ label, value, disabled? }` options. |
| `props.defaultValue` | Pre-selected option.                            |
| `props.orientation`  | `horizontal` or `vertical` layout.              |

## `switch`

An on/off toggle switch with an accessible role.

| Property         | Description                |
| ---------------- | -------------------------- |
| `name`           | Field name.                |
| `props.checked`  | Render in the on position. |
| `props.disabled` | Disable toggling.          |

## `toggle` / `toggle-group`

`toggle` is a single pressable toggle button. `toggle-group` groups several toggles with single- or multiple-selection behavior.

| Property            | Description                                                            |
| ------------------- | ---------------------------------------------------------------------- |
| `name`              | Field name (toggle-group).                                             |
| `props.type`        | `single` or `multiple` (whether one or several toggles can be active). |
| `props.orientation` | `horizontal` or `vertical` (toggle-group).                             |
| `options`           | Toggle options (toggle-group).                                         |

## `slider`

A range input for selecting a numeric value or range.

| Property             | Description             |
| -------------------- | ----------------------- |
| `name`               | Field name.             |
| `props.min`          | Minimum value.          |
| `props.max`          | Maximum value.          |
| `props.step`         | Step increment.         |
| `props.defaultValue` | Initial value or range. |

## `date-picker`

A calendar-based date input.

| Property     | Description                                    |
| ------------ | ---------------------------------------------- |
| `name`       | Field name.                                    |
| `props.mode` | `single` (one date) or `range` (a date range). |
| `props.min`  | Earliest selectable date.                      |
| `props.max`  | Latest selectable date.                        |

## `time-picker`

A time input accepting user-entered time values.

| Property           | Description                               |
| ------------------ | ----------------------------------------- |
| `name`             | Field name.                               |
| `props.timeFormat` | `12h` (shows an AM/PM selector) or `24h`. |
| `props.minTime`    | Earliest selectable time.                 |
| `props.maxTime`    | Latest selectable time.                   |

## `number-input`

A numeric input with stepper buttons.

| Property     | Description                                               |
| ------------ | --------------------------------------------------------- |
| `name`       | Field name.                                               |
| `props.min`  | Minimum value (constrains typed and stepped values).      |
| `props.max`  | Maximum value.                                            |
| `props.step` | Increment amount for stepper buttons and keyboard arrows. |

## `file-upload`

A file selector with optional drag-and-drop.

| Property            | Description                                                             |
| ------------------- | ----------------------------------------------------------------------- |
| `name`              | Field name.                                                             |
| `props.accept`      | Allowed MIME types/extensions (e.g. `image/*,.pdf`).                    |
| `props.maxFiles`    | Maximum number of files that can be selected.                           |
| `props.maxFileSize` | Maximum size in bytes (oversized files are rejected with an error).     |
| `props.dropZone`    | Set `true` to render a drag-and-drop area with a visual drop indicator. |

## `input-otp`

A segmented one-time-password / verification-code input.

| Property       | Description                        |
| -------------- | ---------------------------------- |
| `name`         | Field name.                        |
| `props.length` | Number of code digits/segments.    |
| `props.type`   | Allowed characters (e.g. numeric). |

## `field`

A composed form-field wrapper that renders a label, a control, a description, and an error message as one accessible unit.

| Property           | Description                                                               |
| ------------------ | ------------------------------------------------------------------------- |
| `fieldLabel`       | Label element associated with the child control.                          |
| `fieldDescription` | Help text rendered below the control.                                     |
| `fieldError`       | Error message rendered in the destructive color below the control.        |
| `props.required`   | Show a required indicator (asterisk) on the label.                        |
| `children`         | The wrapped control component, which receives the composed field context. |

```yaml
- type: field
  fieldLabel: 'Email'
  fieldDescription: "We'll never share it."
  props: { required: true }
  children:
    - { type: input, name: email, props: { type: email } }
```

## Related Pages

- [Pages Overview](/en/docs/pages-overview) — the component model and actions.
- [Forms](/en/docs/forms-overview) — standalone form definitions and submission targets.
- [Data Components](/en/docs/data-components) — `data-form` for record-backed forms.
- [Overlay Components](/en/docs/overlay-components) — dialogs and drawers hosting forms.
- [Field Types Overview](/en/docs/field-types-overview) — the table field types forms write to.