---
title: Form fields
description: Add ordered fields to a form and place related fields on one line.
---

A form-fields block is one ordered run of fields inside a form. Each field
submits its value under its resource-field name. The action schema checks the
available names and value types at compile time.

Create this block through `form.fields`. It has no separate factory.

## API

```ts
form.fields(...fields: FieldBuilderContract[]): FormFieldsBuilder
```

| Method  | Input              | Result                                         |
| ------- | ------------------ | ---------------------------------------------- |
| `peers` | `...FieldName[][]` | Replaces the sets of fields that share a line. |

A field that is not in a peer set stands alone. The renderer controls field
width and responsive placement.

## Basic fields

Pass fields in display order. Use `resource.pick` to select existing resource
fields without declaring them again.

<BacklitExample path="form_fields/basic" view="create" />

## Peer fields

Call `peers` with one set of related field names. Other fields in the block
remain on separate lines.

<BacklitExample path="form_fields/peers" view="create" />

## Multiple peer sets

Pass more than one set to create multiple peer rows. Calling `peers` again
replaces all previous sets.

<BacklitExample path="form_fields/all_options" view="create" />

Wrap a form-fields block in a panel or section when the fields need a heading,
description, or visible surface. See [Form](/reference/forms/form) for form
composition and initial values.

## Field roles

`setRoles({ fieldName: role })` selects roles for individual fields and replaces
the previous selections. The default role is `display` in tables and datalists,
and `input` in form field blocks. See [Field roles](/advanced/field-roles).

`revealWhen(condition)` controls the complete block. See [Form conditions](/reference/forms/conditions).