# FormLayout

- Page: https://jiguang132.com/resources/astryx/docs/form-layout
- Resource: Astryx (https://jiguang132.com/resources/astryx.md)
- All guides: https://jiguang132.com/resources/astryx/docs.md

A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go, not state or submission. Wrap it in a <form> for that. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.

## Installation

```bash
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
```

Requires React 19+, base CSS and a Theme provider. See [Setup](/resources/astryx/docs/getting-started).

## Form Layout

A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go, not state or submission. Wrap it in a <form> for that. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.

| Prop | Type | Default | Description |
|---|---|---|---|
| direction | 'vertical' \| 'horizontal' \| 'horizontal-labels' | 'vertical' | Controls field arrangement. Vertical stacks top-to-bottom, horizontal arranges left-to-right with equal flex-grow, and horizontal-labels uses CSS Grid with labels to the left of inputs (collapses to vertical on narrow viewports <=480px). |
| defaultOptionality | 'optional' \| 'required' |  | The state the form treats as its default, so only the exception shows an optional/required indicator. With "optional", only fields marked isRequired show an indicator; with "required", only fields marked isOptional do. A field that restates the default shows nothing. Under "required" the unmarked fields also expose aria-required so screen readers match the visual default; aria-required only, never the native required attribute. Leave unset for today's per-field behavior. |
| children | ReactNode |  | Form fields to arrange. Accepts Astryx inputs (TextInput, Selector, etc.) and Field-wrapped custom controls. |
| xstyle | StyleXStyles |  | StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}. |

### Usage guidance

- Stack fields vertically for most forms. It's the easiest to scan top to bottom.
- Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.
- Use horizontal-labels for settings pages where labels sit beside their inputs.
- Avoid: Use FormLayout for form state or submission. It's just layout. Wrap it in a <form> for that.
- Avoid: Put unrelated fields side by side in a horizontal layout. Save it for fields that belong together.
- Avoid: Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.

### Theming API

```json
{
  "targets": [
    {
      "className": "astryx-form-layout",
      "visualProps": [
        "direction"
      ]
    }
  ]
}
```

### Anatomy

- **Form title**: Heading that describes the purpose of the form.
- **Fields**: Input components with labels for collecting user data.
- **Footer**: Contains confirmation buttons such as Submit or Cancel.


## Examples

- Form Layout: A vertical form layout with text input fields.
- FormLayout — Horizontal: Two fields side by side for naturally paired inputs like first and last name
- FormLayout — Settings Form: Settings form with labels placed beside their inputs
- FormLayout — Mixed Controls: Form with different control types: text input, selector, and checkboxes
- FormLayout — Nested Address Form: Address form mixing vertical and horizontal layouts for grouped fields

---

Index of all JGuang resources: https://jiguang132.com/llms.txt