# components/Form (zidane-ui)

Import: `import { … } from 'zidane-ui'`. Source: [ui/src/components/Form.tsx](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx).

## Components

### `Checkbox`

Component.

The checkbox glyph for multi-select lists; the row around it is the control.

```ts
function Checkbox(props: CheckboxProps): Element
```

**Parameters**

- `props` (`CheckboxProps`): Component props.

**Returns** `Element`

**Props**

- `checked` (`boolean`): Whether the box is ticked.
- `className?` (`string`): Extra classes on the root element.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.

Source: [ui/src/components/Form.tsx:300](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L300)

### `ErrorNote`

Component.

A failure worth reading: a soft danger wash, no border.

```ts
function ErrorNote(props: ErrorNoteProps): Element
```

**Parameters**

- `props` (`ErrorNoteProps`): Component props.

**Returns** `Element`

**Props**

- `children` (`ReactNode`): The error message.
- `className?` (`string`): Extra classes on the root element.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.

Source: [ui/src/components/Form.tsx:63](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L63)

### `FormCard`

Component.

An entity card lifted off its section tray (server, provider, environment).

```ts
function FormCard(props: FormCardProps): Element
```

**Parameters**

- `props` (`FormCardProps`): Component props.

**Returns** `Element`

**Props**

- `children` (`ReactNode`): The card's content.
- `className?` (`string`): Extra classes on the card.
- `data-testid?` (`string`): Test id for the card element.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.

Source: [ui/src/components/Form.tsx:179](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L179)

### `FormSection`

Component.

A labelled group. `rows` (default) hosts flat rows; `cards` spaces raised
`FormCard`s apart on the same tray.

```ts
function FormSection(props: FormSectionProps): Element
```

**Parameters**

- `props` (`FormSectionProps`): Component props.

**Returns** `Element`

**Props**

- `children` (`ReactNode`): The rows or cards.
- `className?` (`string`): Extra classes on the section.
- `layout?` (`'rows' | 'cards'`, default `'rows'`): `rows` hosts flat rows; `cards` spaces raised [`FormCard`](https://zidane.si/docs/reference/ui-components-form.md#FormCard)s apart.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.
- `title?` (`ReactNode`): Label above the section. The label line is omitted when neither `title` nor `trailing` is set.
- `trailing?` (`ReactNode`): Right side of the label line: a count, a small action.

Source: [ui/src/components/Form.tsx:142](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L142)

### `HostRow`

Component.

A row whose one control sits among other buttons (a picker with Test and
clear, a select, a switch beside a note): it washes on hover like a row
button, and a click anywhere on it but on a button or a field works the
control, the element marked `data-row-control` (or the button, select or
input inside it; a select opens its list). Keyboard users reach the
control itself.

```ts
function HostRow(props: HostRowProps): Element
```

**Parameters**

- `props` (`HostRowProps`): The row's `div` attributes, `children` and `disabled`.

**Returns** `Element`

**Props**

- `children` (`ReactNode`): The row's content, the control marked `data-row-control` among it.
- `disabled?` (`boolean`, default `false`): The control can't be used now: no wash, no forwarding.

Source: [ui/src/components/Form.tsx:424](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L424)

### `MetaChip`

Component.

A status or value chip set into its surface: track tone, meta voice.

```ts
function MetaChip(props: MetaChipProps): Element
```

**Parameters**

- `props` (`MetaChipProps`): Component props.

**Returns** `Element`

**Props**

- `children` (`ReactNode`): The chip's content.
- `className?` (`string`): Extra classes on the chip.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.
- `title?` (`string`): Native tooltip.
- `tone?` (`'danger' | 'muted' | 'text' | 'accent' | 'success' | 'warn' | 'info'`, default `'muted'`): Text colour of the chip.

Source: [ui/src/components/Form.tsx:244](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L244)

### `NavRow`

Component.

A row that navigates somewhere (another modal, a sub-surface).

```ts
function NavRow(props: NavRowProps): Element
```

**Parameters**

- `props` (`NavRowProps`): Component props.

**Returns** `Element`

**Props**

- `action` (`{ description: string; icon: string; label: string; onSelect: () => void }`): The row: its `label`, `description` and `icon` class, and `onSelect`, called when the row is
  clicked.
- `className?` (`string`): Extra classes on the root element.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.

Source: [ui/src/components/Form.tsx:388](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L388)

### `OpLine`

Component.

One-line feedback for a lifecycle op (install / update / remove).

```ts
function OpLine(props: OpLineProps): Element
```

**Parameters**

- `props` (`OpLineProps`): Component props.

**Returns** `Element`

**Props**

- `children` (`ReactNode`): The feedback text.
- `className?` (`string`): Extra classes on the root element.
- `kind` (`'error' | 'busy' | 'notice'`): Tone of the line: `busy` and `notice` are muted (a result worth a quiet line,
  never a celebration: a success that shows elsewhere needs no line at all), and
  `error` is danger-coloured and announced as an alert.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.

Source: [ui/src/components/Form.tsx:98](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L98)

### `RowText`

Component.

Label over an optional muted description, the left half of every row.

```ts
function RowText(props: RowTextProps): Element
```

**Parameters**

- `props` (`RowTextProps`): Component props.

**Returns** `Element`

**Props**

- `className?` (`string`): Extra classes on the root element.
- `description?` (`ReactNode`): Muted text under the label.
- `label` (`ReactNode`): The row's main text.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.
- `truncate?` (`boolean`, default `true`): Cut the description to one line with an ellipsis. When off, it wraps.

Source: [ui/src/components/Form.tsx:209](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L209)

### `SegmentedRow`

Component.

Label + description on the left, a Segmented picker on the right.

```ts
function SegmentedRow<T extends string>(props: SegmentedRowProps<T>): Element
```

**Type parameters**

- `T` (`extends string`)

**Parameters**

- `props` (`SegmentedRowProps<T>`): Component props.

**Returns** `Element`

**Props**

- `className?` (`string`): Extra classes on the root element.
- `description?` (`string`): Muted text under the label. It wraps.
- `label` (`string`): The row's main text. It also names the choice group.
- `onChange` (`(v: T) => void`): Called with the new value when an option is picked.
- `options` (`{ disabled?: boolean; icon?: string; label: string; title?: string; value: T }[]`): The choices, as `SegmentedOption`s with a string `label`.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.
- `value` (`T`): The value of the selected option.

Source: [ui/src/components/Form.tsx:515](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L515)

### `SliderRow`

Component.

Labelled range input with a value readout and a reset.

```ts
function SliderRow(props: SliderRowProps): Element
```

**Parameters**

- `props` (`SliderRowProps`): Component props.

**Returns** `Element`

**Props**

- `className?` (`string`): Extra classes on the root element.
- `description?` (`string`): Muted text under the label. It wraps.
- `format` (`(v: number) => string`): Formats the value for the readout beside the slider.
- `label` (`string`): The row's main text. It also names the slider.
- `max` (`number`): Highest value.
- `min` (`number`): Lowest value.
- `onChange` (`(v: number) => void`): Called with the new value while the slider moves.
- `onReset?` (`() => void`): Called when the slider is double-clicked, to restore the default value.
- `step` (`number`): Increment between values.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.
- `value` (`number`): Current value.

Source: [ui/src/components/Form.tsx:563](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L563)

### `Switch`

Component.

The settings-row switch glyph (`SwitchGlyph` md); the row around it is the control.

```ts
function Switch(props: SwitchProps): Element
```

**Parameters**

- `props` (`SwitchProps`): Component props.

**Returns** `Element`

**Props**

- `className?` (`string`): Extra classes on the root element.
- `on` (`boolean`): Whether the switch is on.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.

Source: [ui/src/components/Form.tsx:281](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L281)

### `SwitchRow`

Component.

Plain on/off row for store-backed booleans (not the vendored settings table).

```ts
function SwitchRow(props: SwitchRowProps): Element
```

**Parameters**

- `props` (`SwitchRowProps`): Component props.

**Returns** `Element`

**Props**

- `className?` (`string`): Extra classes on the root element.
- `description?` (`string`): Muted text under the label. It wraps.
- `label` (`string`): The row's main text.
- `on` (`boolean`): Whether the option is on.
- `onToggle` (`() => void`): Called when the row is clicked.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.

Source: [ui/src/components/Form.tsx:476](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L476)

### `ToggleSwitch`

Component.

A standalone switch control, for rows that host other buttons too.

```ts
function ToggleSwitch(props: ToggleSwitchProps): Element
```

**Parameters**

- `props` (`ToggleSwitchProps`): Component props.

**Returns** `Element`

**Props**

- `className?` (`string`): Extra classes on the root element.
- `disabled?` (`boolean`, default `false`): Grey the switch out and ignore clicks.
- `label` (`string`): Accessible name of the switch. It has no visible text.
- `on` (`boolean`): Whether the switch is on.
- `onChange` (`(on: boolean) => void`): Called with the new state when the switch is clicked.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.
- `title?` (`string`): Native tooltip.

Source: [ui/src/components/Form.tsx:347](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L347)

## Constants

### `FIELD_LABEL_CLASS`

Constant.

Label above a form field.

```ts
const FIELD_LABEL_CLASS = 'block text-xs text-[var(--zg-text-muted)] mb-1'
```

Source: [ui/src/components/Form.tsx:43](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L43)

### `FORM_CARD_CLASS`

Constant.

An inline add / install form: a raised card above the list it feeds.

```ts
const FORM_CARD_CLASS = 'zg-raised border rounded-zg-lg p-4 space-y-3'
```

Source: [ui/src/components/Form.tsx:46](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L46)

### `INPUT_CLASS`

Constant.

Single-line text input: a well set into its surface.

```ts
const INPUT_CLASS: 'zg-well w-full h-8 px-2.5 text-zg-ui placeholder:text-[var(--zg-text-subtle)] disabled:opacity-zg-disabled'
```

Source: [ui/src/components/Form.tsx:35](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L35)

### `ROW_BUTTON_CLASS`

Constant.

A whole-row button inside a section tray: flat, washed on hover.

```ts
const ROW_BUTTON_CLASS = ...
```

Source: [ui/src/components/Form.tsx:20](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L20)

### `ROW_CLASS`

Constant.

A static row whose control (segment, slider, input) takes the input.

```ts
const ROW_CLASS = 'flex items-center gap-3 px-3 py-2'
```

Source: [ui/src/components/Form.tsx:23](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L23)

### `ROW_HOST_CLASS`

Constant.

A [`HostRow`](https://zidane.si/docs/reference/ui-components-form.md#HostRow)'s surface: a row button's wash, giving with the control inside (`zg-press-host`).

```ts
const ROW_HOST_CLASS = ...
```

Source: [ui/src/components/Form.tsx:26](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L26)

### `ROW_TRIGGER_CLASS`

Constant.

The control of a [`HostRow`](https://zidane.si/docs/reference/ui-components-form.md#HostRow) that takes the row's width: a picker's trigger, holding the label and the value.

```ts
const ROW_TRIGGER_CLASS = ...
```

Source: [ui/src/components/Form.tsx:29](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L29)

### `TEXTAREA_CLASS`

Constant.

Multi-line / code input.

```ts
const TEXTAREA_CLASS: 'zg-well w-full px-2.5 py-2 text-zg-label font-mono leading-relaxed placeholder:text-[var(--zg-text-subtle)] resize-y'
```

Source: [ui/src/components/Form.tsx:39](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L39)

## Interfaces

### `CheckboxProps`

Interface.

Props for [`Checkbox`](https://zidane.si/docs/reference/ui-components-form.md#Checkbox).

```ts
interface CheckboxProps
```

**Properties**

- `checked` (`boolean`): Whether the box is ticked.
- `className?` (`string`): Extra classes on the root element.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.

Source: [ui/src/components/Form.tsx:286](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L286)

### `ErrorNoteProps`

Interface.

Props for [`ErrorNote`](https://zidane.si/docs/reference/ui-components-form.md#ErrorNote).

```ts
interface ErrorNoteProps
```

**Properties**

- `children` (`ReactNode`): The error message.
- `className?` (`string`): Extra classes on the root element.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.

Source: [ui/src/components/Form.tsx:49](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L49)

### `FormCardProps`

Interface.

Props for [`FormCard`](https://zidane.si/docs/reference/ui-components-form.md#FormCard).

```ts
interface FormCardProps
```

**Properties**

- `children` (`ReactNode`): The card's content.
- `className?` (`string`): Extra classes on the card.
- `data-testid?` (`string`): Test id for the card element.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.

Source: [ui/src/components/Form.tsx:163](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L163)

### `FormSectionProps`

Interface.

Props for [`FormSection`](https://zidane.si/docs/reference/ui-components-form.md#FormSection).

```ts
interface FormSectionProps
```

**Properties**

- `children` (`ReactNode`): The rows or cards.
- `className?` (`string`): Extra classes on the section.
- `layout?` (`'rows' | 'cards'`, default `'rows'`): `rows` hosts flat rows; `cards` spaces raised [`FormCard`](https://zidane.si/docs/reference/ui-components-form.md#FormCard)s apart.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.
- `title?` (`ReactNode`): Label above the section. The label line is omitted when neither `title` nor `trailing` is set.
- `trailing?` (`ReactNode`): Right side of the label line: a count, a small action.

Source: [ui/src/components/Form.tsx:116](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L116)

### `HostRowProps`

Interface.

Props for [`HostRow`](https://zidane.si/docs/reference/ui-components-form.md#HostRow): the row's `div` attributes, `children` and `disabled`.

```ts
interface HostRowProps extends HTMLAttributes<HTMLDivElement>
```

**Properties**

- `children` (`ReactNode`): The row's content, the control marked `data-row-control` among it.
- `disabled?` (`boolean`, default `false`): The control can't be used now: no wash, no forwarding.

Source: [ui/src/components/Form.tsx:404](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L404)

### `MetaChipProps`

Interface.

Props for [`MetaChip`](https://zidane.si/docs/reference/ui-components-form.md#MetaChip).

```ts
interface MetaChipProps
```

**Properties**

- `children` (`ReactNode`): The chip's content.
- `className?` (`string`): Extra classes on the chip.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.
- `title?` (`string`): Native tooltip.
- `tone?` (`'danger' | 'muted' | 'text' | 'accent' | 'success' | 'warn' | 'info'`, default `'muted'`): Text colour of the chip.

Source: [ui/src/components/Form.tsx:223](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L223)

### `NavRowProps`

Interface.

Props for [`NavRow`](https://zidane.si/docs/reference/ui-components-form.md#NavRow).

```ts
interface NavRowProps
```

**Properties**

- `action` (`{ description: string; icon: string; label: string; onSelect: () => void }`): The row: its `label`, `description` and `icon` class, and `onSelect`, called when the row is
  clicked.
- `className?` (`string`): Extra classes on the root element.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.

Source: [ui/src/components/Form.tsx:371](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L371)

### `OpLineProps`

Interface.

Props for [`OpLine`](https://zidane.si/docs/reference/ui-components-form.md#OpLine).

```ts
interface OpLineProps
```

**Properties**

- `children` (`ReactNode`): The feedback text.
- `className?` (`string`): Extra classes on the root element.
- `kind` (`'error' | 'busy' | 'notice'`): Tone of the line: `busy` and `notice` are muted (a result worth a quiet line,
  never a celebration: a success that shows elsewhere needs no line at all), and
  `error` is danger-coloured and announced as an alert.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.

Source: [ui/src/components/Form.tsx:78](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L78)

### `RowTextProps`

Interface.

Props for [`RowText`](https://zidane.si/docs/reference/ui-components-form.md#RowText).

```ts
interface RowTextProps
```

**Properties**

- `className?` (`string`): Extra classes on the root element.
- `description?` (`ReactNode`): Muted text under the label.
- `label` (`ReactNode`): The row's main text.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.
- `truncate?` (`boolean`, default `true`): Cut the description to one line with an ellipsis. When off, it wraps.

Source: [ui/src/components/Form.tsx:188](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L188)

### `SegmentedRowProps`

Interface.

Props for [`SegmentedRow`](https://zidane.si/docs/reference/ui-components-form.md#SegmentedRow).

```ts
interface SegmentedRowProps<T extends string>
```

**Type parameters**

- `T` (`extends string`)

**Properties**

- `className?` (`string`): Extra classes on the root element.
- `description?` (`string`): Muted text under the label. It wraps.
- `label` (`string`): The row's main text. It also names the choice group.
- `onChange` (`(v: T) => void`): Called with the new value when an option is picked.
- `options` (`{ disabled?: boolean; icon?: string; label: string; title?: string; value: T }[]`): The choices, as `SegmentedOption`s with a string `label`.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.
- `value` (`T`): The value of the selected option.

Source: [ui/src/components/Form.tsx:493](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L493)

### `SliderRowProps`

Interface.

Props for [`SliderRow`](https://zidane.si/docs/reference/ui-components-form.md#SliderRow).

```ts
interface SliderRowProps
```

**Properties**

- `className?` (`string`): Extra classes on the root element.
- `description?` (`string`): Muted text under the label. It wraps.
- `format` (`(v: number) => string`): Formats the value for the readout beside the slider.
- `label` (`string`): The row's main text. It also names the slider.
- `max` (`number`): Highest value.
- `min` (`number`): Lowest value.
- `onChange` (`(v: number) => void`): Called with the new value while the slider moves.
- `onReset?` (`() => void`): Called when the slider is double-clicked, to restore the default value.
- `step` (`number`): Increment between values.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.
- `value` (`number`): Current value.

Source: [ui/src/components/Form.tsx:533](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L533)

### `SwitchProps`

Interface.

Props for [`Switch`](https://zidane.si/docs/reference/ui-components-form.md#Switch).

```ts
interface SwitchProps
```

**Properties**

- `className?` (`string`): Extra classes on the root element.
- `on` (`boolean`): Whether the switch is on.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.

Source: [ui/src/components/Form.tsx:267](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L267)

### `SwitchRowProps`

Interface.

Props for [`SwitchRow`](https://zidane.si/docs/reference/ui-components-form.md#SwitchRow).

```ts
interface SwitchRowProps
```

**Properties**

- `className?` (`string`): Extra classes on the root element.
- `description?` (`string`): Muted text under the label. It wraps.
- `label` (`string`): The row's main text.
- `on` (`boolean`): Whether the option is on.
- `onToggle` (`() => void`): Called when the row is clicked.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.

Source: [ui/src/components/Form.tsx:456](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L456)

### `ToggleSwitchProps`

Interface.

Props for [`ToggleSwitch`](https://zidane.si/docs/reference/ui-components-form.md#ToggleSwitch).

```ts
interface ToggleSwitchProps
```

**Properties**

- `className?` (`string`): Extra classes on the root element.
- `disabled?` (`boolean`, default `false`): Grey the switch out and ignore clicks.
- `label` (`string`): Accessible name of the switch. It has no visible text.
- `on` (`boolean`): Whether the switch is on.
- `onChange` (`(on: boolean) => void`): Called with the new state when the switch is clicked.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.
- `title?` (`string`): Native tooltip.

Source: [ui/src/components/Form.tsx:322](https://github.com/Tahul/zidane/blob/main/ui/src/components/Form.tsx#L322)