Edit page

FormLayout

The FormLayout aligns form fields into an organized grid.

Basic Usage

To implement the FormLayout component, you need to import it first:

import { FormLayout } from '@react-ui-org/react-ui';

And use it:

See API for all available options.

General Guidelines

Since all form fields in React UI are styled as inline blocks, they queue up one after another in a row by default. The FormLayout component is there to make building vertical and horizontal forms easy. It uses the right tool for the job: the CSS grid layout.

  • Put only form field components from React UI inside the FormLayout and make sure they are direct descendants of it (React fragments are supported!). All React UI form components are ready for this use case and don't need to be wrapped in any divs. Namely, the FormLayout supports the following React UI components: CheckboxField, Radio, SelectField, TextArea, TextField, and Toggle.

  • Use the FormLayoutCustomField component when you need to place any custom content inside the FormLayout. This layout helper ensures your content is properly spaced and aligned with other FormLayout elements. Do not try to put any custom HTML or React components directly into FormLayout without wrapping it with the FormLayoutCustomField first.

👉 For usage in auto-width Modal, you may need to turn on the autoWidth option for your FormLayout. This prevents FormLayout from unexpectedly growing in browsers that don't support CSS subgrid in cases when there are longer validation messages or help texts.

Vertical Layout

Vertical FormLayout works similar to single-column Grid layout while it also forces vertical layout mode on form fields. To use this layout, simply wrap your form fields with the FormLayout component:

Horizontal Layout

Horizontal FormLayout is designed for horizontal form fields: it nicely aligns labels and inputs in an organized grid. It is applied starting from the md viewport size onward and it forces the horizontal layout on the fields.

Label Width

In the horizontal layout mode, it's possible to fine-tune the way how the form will be aligned through the labelWidth option to cover various design requirements. It comes with three globally shared options: default width, auto width, and limited width. For cases where an individual manual width works better, there is the local custom width mode which enables setting a width that is applied just for the current FormLayout.

👉 All global label width options can be easily customized with CSS custom properties.

Label Width Options

  • The default mode (global) sets the width of all labels to a global default value which is 10 em.

  • The auto mode (global) aligns the form according to the longest label.

  • The limited mode (global) works as auto except it's intended for values that set a limit for the label width. Its default value is fitcontent(50%) which also aligns the form according to the longest label like auto, but with the difference that the labels cannot be wider than 50 % of the FormLayout.

  • The custom mode (local) allows you to enter any custom label width for individual FormLayouts.

📐 Try resizing the playground to see how individual options work.

Limitations

Label Position

Label position of inline form fields (CheckboxField, Toggle) is ignored in horizontal FormLayout.

Modals

Please note the auto and limited label width options may not function correctly in combination with other auto layout mechanisms, e.g. the auto-width Modal. It's just too much of magic that does not quite work together yet 🎩.

Custom Fields

You can even place any content you need into the FormLayout — just wrap it with the FormLayoutCustomField component. This layout helper ensures your content is properly spaced and aligned with to other FormLayout elements. FormLayoutCustomFields are designed to work solely inside the FormLayout component.

👉 While you can set FormLayoutCustomField as disabled, valid or required and its styles may affect contained form fields through CSS cascade, don't forget to mirror the aforementioned properties to the contained form fields too as API options as such are not inherited.

Label Alignment

If you are in a situation with one or more box form fields inside your FormLayoutCustomField, you may want to have its label aligned with the fields inside. Since it's not quite possible to do this automatically due to limited browser support, there is innerFieldSize option which accepts any of existing box field sizes (small, medium, or large) and is intended right for this task.

Validation States

Custom fields support the same validation states as regular form fields to provide labels with optional feedback style.

Accessibility

If possible, use the labelForId option to provide ID of contained form field so the field remains accessible via custom field label.

You can also specify size of contained form field so custom field label is properly vertically aligned.

Full Example

This is a demo of all components supported by FormLayout.

Forwarding HTML Attributes

In addition to the options below in the component's API section, you can specify React synthetic events or any HTML attribute you like. All attributes that don't interfere with the API are forwarded to the root <div> HTML element. This enables making the component interactive and helps to improve its accessibility.

👉 Refer to the MDN reference for the full list of supported attributes of the div element.

API

Prop nameTypeDefaultRequiredDescription
autoWidthboolfalsefalse

If true, FormLayout will take up only as much horizontal space as necessary.

childrennodenullfalse

Supported form field components:

  • CheckboxField
  • FileInputField
  • FormLayoutCustomField
  • Radio
  • SelectField
  • TextArea
  • TextField
  • Toggle

If none are provided nothing is rendered.

fieldLayout'horizontal' │ 'vertical''vertical'false

Layout that is forced on children form fields.

labelWidth'auto' │ 'default' │ 'limited' │ string'default'false

Width of the column with form field labels. Only available if the fieldLayout is set to horizontal.

FormLayoutCustomField API

A place for custom content inside FormLayout.

Prop nameTypeDefaultRequiredDescription
childrennodenullfalse

Custom HTML or React component(s). If none are provided nothing is rendered.

disabledboolfalsefalse

If true, label will be shown as disabled.

fullWidthboolfalsefalse

If true, the field will span the full width of its parent.

idstringundefinedfalse

ID of the root HTML element.

Also serves as base for ids of nested elements:

  • <ID>__field
  • <ID>__label
innerFieldSize'small' │ 'medium' │ 'large'nullfalse

Size of contained form field used to properly align label.

labelstringnullfalse

Optional label of the field.

labelForIdstringundefinedfalse

Optional ID of labeled field to keep accessibility features. Only available if label is set.

requiredboolfalsefalse

If true, label will be styled as required.

validationState'invalid' │ 'valid' │ 'warning'nullfalse

Alter the field to provide feedback based on validation result.

Theming

Custom PropertyDescription
--rui-FormLayout__row-gapGap between individual rows
--rui-FormLayout--horizontal__label__widthDefault label width
--rui-FormLayout--horizontal__label__width--autoLabel width in automatic layout
--rui-FormLayout--horizontal__label__width--limitedLabel width in limited-width layout

FormLayoutCustomField Theming

FormLayoutCustomField can be styled using a small subset of other form fields theming options.

Custom PropertyDescription
--rui-FormField--custom--default__surrounding-text-colorCustom field label color in default state
--rui-FormField--custom--disabled__surrounding-text-colorCustom field label color in disabled-like state