FormLayout
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
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.
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
{
"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