# Field > A label, a control, a description and the binding's error messages, wired together from one th:field. Source: https://shadleaf.dev/current/components/field/ **Example: Field.** ```html

Username

Letters, digits and dashes.

``` ## One th:field for the whole field Put `th:field` on ``, not on the control. The field reads the binding and hands it to its parts, so you write the field once and get: - the control bound to the field: `name`, value and `id`, as `th:field` on the control would give; - `` with a `for` that points at the control; - `` with an `id`, and the control's `aria-describedby` pointing at it; - `` showing the binding's messages, and the control described by them while there are any; - `aria-invalid` on the control and `data-invalid` on the field when the binding has errors. ```html ``` With an error on `email`, that renders: ```html

We never share it.

must be a well-formed email address

``` The parts go in any order. A field holds one control: a second one keeps its own `th:field` and id. ## Errors `` renders nothing while the field has no errors. One message is shown as text, several as a list, each message once. Content of your own replaces the messages and always shows, so wrap it in a `th:if` when it should only show with errors. **Example: With errors.** A second submit renders the form again. The field shows the binding's messages and is marked data-invalid; the input is aria-invalid and described by the message. ```html

Work email

Your company address.

``` **Example: Several errors.** ```html

Password

``` The error has no `role="alert"`. After a submit the whole page loads again, and a screen reader would read out every error at once. The control is `aria-invalid` and described by its error instead, so the message is read when the user reaches the control. When htmx swaps the whole form in, `` moves focus to the first control with an error, which reads it out; see [Forms with htmx](https://shadleaf.dev/current/guides/htmx.md). If you swap a single field in while focus stays elsewhere, for example to validate it as the user leaves it, add `role="alert"` to its error yourself. Errors that belong to the whole form rather than one field, such as `reject(...)` in the controller, go in a [``](https://shadleaf.dev/current/components/form-errors.md) above the fields. ## Ids The control's id is the field's name, the id `th:field` gives a text input: `email`, or `address.street` for a nested property. The description and error ids add `-description` and `-error`. Set `for` on the field to use another id: ```html ``` An `aria-describedby` you put on the control is kept, and the field's ids are added after it. For a checkbox or switch, Spring numbers the id (`terms1`), so that several checkboxes bound to one list field get different ids. In a field, the checkbox gets the field's name instead, and the label points at it. ## Other controls A textarea and a native select work as the input does: **Example: Textarea.** ```html

Bio

A few words for your profile page.

``` **Example: Native select.** ```html

Country

``` ## Checkbox and switch `orientation="horizontal"` puts the control first and the label beside it. `` stacks the label with a description or an error. **Example: Switch.** A horizontal field puts the control first. field-content stacks the label with its description. ```html

Product updates

One email a month, no more.

``` **Example: Checkbox.** In a field, the checkbox gets the field's name as its id, not Spring's numbered one, so the label points at it. ```html

I accept the terms and conditions

``` ## Radio buttons and checkbox groups A set of options that answers one question is a ``, with a `` as its question. `th:field` goes on the field set, and the options inside share it. A description and an error directly inside the field set describe the whole group: the `fieldset` gets the `aria-describedby`, while each radio button is still marked `aria-invalid` from the field. **Example: Radio group.** The field-set holds the th:field, which its radio buttons share. The description and the error describe the fieldset. ```html

Plan

You can change it at any time.

Monthly

Yearly

``` For checkboxes, make each option a horizontal field without a `th:field` of its own. It takes the field set's, and the next of Spring's numbered ids (`toppings1`, `toppings2`), which its label points at. **Example: Checkbox group.** Each option is a field without th:field of its own. It takes the field-set's, with the next of Spring's numbered ids. ```html

Toppings

Cheese

Olives

Basil

``` `variant="label"` on the legend gives it the size of a field label; the default is a section heading. ## Layout `` stacks fields with even spacing. A field set without `th:field` groups related fields under a heading. **Example: Field set and field group.** ```html

Shipping address

Where we deliver your order.

Street

City

``` `orientation="responsive"` puts the label and the control side by side when the enclosing field group is at least 28rem wide, and stacks them when it is narrower. **Example: Responsive.** Side by side in a wide field-group, stacked in a narrow one. ```html

Display name

Shown next to your comments.

``` ## Disabled and read-only A field notices a disabled control inside it and fades its label: there is no `data-disabled` to set, as there is in shadcn. The description keeps its colour, since it often says why the control is disabled. **Example: Disabled.** The label fades with a disabled control, found by the field itself; the description stays legible, as it often says why. ```html

Company name

Only an administrator can change it.

Two-factor authentication

Required by your organisation.

``` `disabled` on a `` disables every control in it, as it does on any `fieldset`. The legend and the options' labels fade with them. **Example: Disabled field set.** disabled on the field set disables every control in it, as on a fieldset; the legend and labels fade with them. ```html

Billing cycle

Fixed until your contract ends.

Monthly

Yearly

``` A read-only control changes nothing in the field: its label stays as it is. See the [input](https://shadleaf.dev/current/components/input.md#read-only) for how it looks. **Example: Read-only.** A read-only input keeps its label as it is. It still takes focus, and its value is submitted. ```html

Account number

Quote it when you contact us.

``` A disabled control is not submitted, so an error on it usually comes from something the user cannot change in this form. It still shows: the control keeps its destructive border, faded, next to the field's error. With ``, a control with a `disabled` attribute is passed over and the next control with errors takes the focus; one disabled by `th:disabled` or by a disabled field set is not known to be disabled when the page is rendered, and then nothing takes the focus. ## Without th:field A field without `th:field` is only layout. Set `for` to give the control its id, the label its `for`, and the description and error their ids. Without a binding, `data-invalid` and `aria-invalid` are yours to set. **Example: Without th:field.** for gives the control its id, and the description and error their ids. ```html

Search orders

An order number or a customer name.

``` ## How the parts find the field `` renders its content with a local variable, `slField`, that holds the `th:field`, the ids and the messages. Every part and control inside it reads that variable, which is why nothing has to be repeated. To know whether it has a description or an error, the field looks at its content as written: a part added with `th:replace` is not seen, and a part with a `th:if` that is false still counts, so the control would point at a description that is not there. ## Attributes ### sl:field Attributes of ``: A form field: a `sl:field-label`, one control, and optionally a `sl:field-description` and a `sl:field-error`, in any order. Put `th:field` on the field, not on the control: the control takes it, gets the `id` the label points at (the field's name, `email`, also for a checkbox or switch), and an `aria-describedby` listing the description and, when the binding has errors, the error. The error shows the binding's messages. A field with errors gets `data-invalid`. Without `th:field`, set `for` to the control's id. | Attribute | Values | Default | Description | | --- | --- | --- | --- | | `orientation` | `vertical`, `horizontal`, `responsive` | `vertical` | Stack the label above the control, or put them side by side (a checkbox or switch, then its label). `responsive` stacks them in a narrow `sl:field-group` and puts them side by side in a wide one. | | `for` | *string* | — | The id of the control: for a field without `th:field`, or to use another id than the field's name. The control gets it when it has no id of its own, and the description and error ids derive from it. | Every prop can also be set from an expression: `th:orientation="${...}"`. Any other attribute passes through to the rendered element, and `class` is appended. ### sl:field-label Attributes of ``: The label of a `sl:field`. Its `for` points at the field's control; a `for` of your own wins. `sl:field-label` declares no props; every attribute passes through. ### sl:field-description Attributes of ``: Help text for a `sl:field` or `sl:field-set`. It gets the id the control's (or fieldset's) `aria-describedby` points at. `sl:field-description` declares no props; every attribute passes through. ### sl:field-error Attributes of ``: The error messages of a `sl:field` or `sl:field-set`, read from its `th:field`'s binding: one message as text, several as a list. It renders nothing while there are none. Content of its own replaces the messages, and always shows. It gets the id the control's (or fieldset's) `aria-describedby` points at while it shows messages. `sl:field-error` declares no props; every attribute passes through. ### sl:field-content Attributes of ``: Stacks a `sl:field-label` with its `sl:field-description` or `sl:field-error`, beside the control of a horizontal `sl:field`. `sl:field-content` declares no props; every attribute passes through. ### sl:field-set Attributes of ``: A group of related fields or options under a `sl:field-legend`, as a `fieldset`. With `th:field`, the options inside share it: radio buttons in a `sl:radio-group`, or checkboxes each in a `sl:field` of their own (which then need no `th:field` and get Spring's numbered ids, `toppings1`). A `sl:field-description` and `sl:field-error` directly inside describe the fieldset, and it gets `data-invalid` when the binding has errors. `sl:field-set` declares no props; every attribute passes through. ### sl:field-legend Attributes of ``: The caption of a `sl:field-set`, as its `legend`. Put it first in the fieldset. | Attribute | Values | Default | Description | | --- | --- | --- | --- | | `variant` | `legend`, `label` | `legend` | A section heading, or the size of a field label (for a set of options that answers one question). | Every prop can also be set from an expression: `th:variant="${...}"`. Any other attribute passes through to the rendered element, and `class` is appended. ### sl:field-group Attributes of ``: Stacks `sl:field`s and `sl:field-set`s with even spacing. Fields with `orientation="responsive"` inside it go side by side when it is wide enough. `sl:field-group` declares no props; every attribute passes through.