# Field

> A settings row: title and description left, control right. A native Pyzed component for Python desktop GUIs, with a live preview, code examples and its API.

Source: https://albakore.github.io/pyzed/library/field/

:::tip[In plain words]
A row of a form: the name of a setting on the left and its control on the right.
:::

A form row like the ones of a settings screen: the title (and an optional description) on the left and any control on the right. Stack several in a column or a [Settings group](https://albakore.github.io/pyzed/library/settings-group/).

`ui.field` · Category: [Forms](https://albakore.github.io/pyzed/library/#forms) · [Full reference →](https://albakore.github.io/pyzed/reference/ui/#field)

**Code:**

```python
pz.column([
    ui.field("Autosave", ui.switch(True, on_toggle), description="Saves when you switch tabs"),
    ui.field("Format on save", ui.checkbox(False, on_toggle)),
    ui.field("Font size", ui.number_field(14, on_change, suffix="px")),
], spacing=14, width=440)
```

## When to use

- For preferences and forms where each control needs a label and maybe a hint.
- It lines up switches, selects and number fields of different widths.

## Usage

```python
import pyzed as pz
from pyzed import ui

pz.column([
    ui.field("Autosave", ui.switch(True, on_toggle), description="Saves when you switch tabs"),
    ui.field("Format on save", ui.checkbox(False, on_toggle)),
    ui.field("Font size", ui.number_field(14, on_change, suffix="px")),
], spacing=14, width=440)
```

## Variants

:::note[About these captures]
Each capture is recorded by pyzed itself, off-screen at 2x, in One Dark or One Light to match this site's theme, and cropped to the component so it shows at its real size. The pointer hovers, presses or types into it; a component that does not react to the pointer cycles through a few themes. With reduced motion you see the first frame. Open **Code** under a capture to see the snippet that draws it; free names such as `on_save` stand for your own callbacks.
:::

### Control

```python
pz.container(ui.field("Autosave", ui.switch(True, on_toggle)), width=380)
```

```python
pz.container(ui.field("Font size", ui.number_field(14, on_change, suffix="px")), width=380)
```

```python
pz.container(ui.field("Theme", ui.select(["One Dark", "One Light"], "One Dark", on_select, width=150)), width=380)
```

```python
pz.container(ui.field("Name", ui.input("Pyzed", on_input, width=180)), width=380)
```

### Help and errors

```python
pz.container(ui.field("Autosave", ui.switch(True, on_toggle), description="Saves when you switch tabs"), width=380)
```

```python
pz.container(ui.field("Port", ui.number_field(80, on_change), error="Ports below 1024 need admin rights"), width=380)
```

### States and events

```python
pz.container(ui.field("Name", ui.input("", on_input, width=180), required=True), width=380)
```

```python
pz.container(ui.field("Email", ui.input("ada@", on_input, invalid=True), vertical=True, required=True,
                      error="Enter a valid email"), width=320)
```

## Events

Field has no events of its own: it shows what you give it. Like every widget it also has the **18 common events** (`click`, `double_click`, `right_click`, `mouse_enter`, `drag`, `key_down`, `resize`…), attached with `.on(...)`: see [Events](https://albakore.github.io/pyzed/guides/events/) and [Events of every component](https://albakore.github.io/pyzed/library/events/).

## Properties and API

### `ui.field`

```python
field(
    title,
    control,
    *,
    description=None,
    error=None,
    required=False,
    vertical=False,
    theme=None,
)
```

A form row: title and description on the left, control on the right (like a settings screen).

| Property | Default | Description |
| --- | --- | --- |
| `title` | *required* | Title. |
| `control` | *required* | The control (switch, input…). |
| `description` | `None` | Help text. |
| `error` | `None` | A validation message shown under the title in the error color (see `pz.validation_errors`). |
| `required` | `False` | Adds a red `*` after the title. |
| `vertical` | `False` | Puts the control under the title. |
| `theme` | `None` | Theme to use instead of the current one (`pyzed.theme.current()`). |

[Full reference →](https://albakore.github.io/pyzed/reference/ui/#field)

## Related

- [Settings group](https://albakore.github.io/pyzed/library/settings-group/): A titled block of field rows, for settings screens.
- [Switch](https://albakore.github.io/pyzed/library/switch/): An on/off switch for settings that apply at once.
- [Number field](https://albakore.github.io/pyzed/library/number-field/): A number with −/+ buttons, limits, step and suffix.