Form layouts
Be sure to read the full forms usage guidelines.
Form and form rows
Use the EuiFormRow component to easily associate form components with labels, help text, and error text. Use the EuiForm component to group EuiFormRows. By default EuiForm will render as a simple div unless you pass component="form".
Full-width
Form elements will automatically flex to a max-width of 400px. You can optionally pass the fullWidth prop to the row and form control to expand to their container. This should be done rarely and usually you will only need it for isolated controls like search bars and sliders.
Global full-width
To set all the row and controls in a form to fullWidth, specify the prop on the root EuiForm component.
Inline
Inline forms can be made with EuiFlexGroup. Apply grow={false} on any of the items you want to collapse (like the button below). Note that the button's EuiFormRow wrapper also requires an additional prop when it’s missing a label hasEmptyLabelSpace.
Sizing inline form rows
Apply a width or change the grow prop on the wrapping EuiFlexItem to size individual controls. When you need to make a field smaller, always apply the width to the flex item, not the input. The input inside will resize as needed.
When supplying children to an EuiFormRow that is not a form control, and you need to the content to vertically center with the other form controls, change the display prop to center or centerCompressed.
Described form groups
Use EuiDescribedFormGroup component to create sections of associated form controls and rows. It can also simply be used with one EuiFormRow as a way to display additional text next to the field (on mobile, it will revert to being stacked).
Read more about appropriate layout usage of EuiDescribedFormGroup in the forms usage guidelines.
Sizing described form rows
By default, EuiDescribedFormGroup has a max-width of 800px for best readability. To expand the group to 100%, add the fullWidth prop to this, the EuiFormRow, and the individual fields.
You can also change the ratio of the width of the description column versus the field column. By default it is 'half', but you can also change to 'third' or 'quarter' which prioritizes the field column. You will most likely still need to apply fullWidth to all the components. The description column does have a minimum readable width applied to it so that it cannot shrink too far.
Both the description and field columns are simply EuiFlexItem wrappers. If you need more customization of these columns you can pass flex item props to descriptionFlexItemProps and fieldFlexItemProps respectively.
Form labels
The best way to provide an accessible name to form elements is to use the label prop provided by EuiFormRow. However, certain types of form controls require extra care to ensure an accessible experience. Below are just a few examples.
Form controls that come with their own label don‘t need the one provided by EuiFormRow. For controls like EuiSwitch, EuiButton, and EuiLink be sure to pass hasChildLabel={false} to the wrapping EuiFormRow.
Implicit titles for the first form control
When displaying the form control's name in some other way than through the visual label prop, the form control still needs to be associated with that element. To do this, either:
- duplicate the text and pass it as the
aria-labelof the form control, or - pass the
idof the text to the form control'saria-labelledby.
More complicated form labels
Some controls are just hard though and will often require some custom work. Refer to an individual component‘s documentation and remember to test with a screen reader!
In a popover
Because forms auto-size to their wrapping elements, it means you can do fun things with them like stuff them in popovers and they’ll still work perfectly.
Props
EuiForm
Prop | Description and type | Default value |
|---|---|---|
Prop className# | Description and type Type: string | Default value |
Prop aria-label# | Description and type Defines a string value that labels the current element. string | Default value |
Prop data-test-subj# | Description and type Type: string | Default value |
Prop css# | Description and type Type: Interpolation<Theme> | Default value |
Prop component# | Description and type Which HTML element to render "div" | "form" | Default value div |
Prop isInvalid# | Description and type Type: boolean | Default value |
Prop error# | Description and type Type: ReactNode | ReactNode[] | Default value |
Prop invalidCallout# | Description and type Where to display the callout with the list of errors "none" | "above" | Default value above |
Prop fullWidth# | Description and type When set to boolean | Default value false |
Prop ref# | Description and type Allows getting a ref to the component instance. LegacyRef<HTMLElement> | Default value |
EuiFormRow
Prop | Description and type | Default value |
|---|---|---|
Prop labelType# | Description and type Defaults to rendering a "label" | "legend" | Default value label |
Prop className# | Description and type Type: string | Default value |
Prop aria-label# | Description and type Defines a string value that labels the current element. string | Default value |
Prop data-test-subj# | Description and type Type: string | Default value |
Prop css# | Description and type Type: Interpolation<Theme> | Default value |
Prop display# | Description and type
"center" | "row" | "columnCompressed" | "centerCompressed" | "rowCompressed" | Default value row |
Prop hasEmptyLabelSpace# | Description and type Useful for inline form layouts, primarily for content that boolean | Default value false |
Prop fullWidth# | Description and type Expand to fill 100% of the parent. boolean | Default value false |
Prop describedByIds# | Description and type IDs of additional elements that should be part of children's string[] | Default value |
Prop hasChildLabel# | Description and type Escape hatch to not render duplicate labels if the child also renders a label boolean | Default value true |
Prop children# | Description and type ReactElement to render as this component's content ReactElement<any, string | JSXElementConstructor<any>> & ReactNode | Default value |
Prop label# | Description and type Type: ReactNode | Default value |
Prop labelAppend# | Description and type Adds an extra node to the right of the form label without any | Default value |
Prop id# | Description and type Type: string | Default value |
Prop isInvalid# | Description and type Type: boolean | Default value |
Prop error# | Description and type Type: ReactNode | ReactNode[] | Default value |
Prop helpText# | Description and type Adds a single node/string or an array of nodes/strings below the input ReactNode | ReactNode[] | Default value |
Prop isDisabled# | Description and type Passed along to the label element; and to the child field element when boolean | Default value |
EuiDescribedFormGroup
Prop | Description and type | Default value |
|---|---|---|
Prop title# | Description and type For better accessibility, it's recommended to use an HTML heading. ReactElement | Default value Required |
Prop className# | Description and type Type: string | Default value |
Prop aria-label# | Description and type Defines a string value that labels the current element. string | Default value |
Prop data-test-subj# | Description and type Type: string | Default value |
Prop css# | Description and type Type: Interpolation<Theme> | Default value |
Prop children# | Description and type One or more ReactNode | Default value |
Prop gutterSize# | Description and type Passed to "xs" | "s" | "m" | "l" | "xl" | "none" | Default value l |
Prop fullWidth# | Description and type Expand to fill 100% of the parent. boolean | Default value false |
Prop ratio# | Description and type Width ratio of description column compared to field column. "half" | "third" | "quarter" | Default value half |
Prop titleSize# | Description and type Adjust the visual "xs" | "s" | "m" | "l" | "xxxs" | "xxs" | Default value xs |
Prop description# | Description and type Added as a child of ReactNode | Default value |
Prop descriptionFlexItemProps# | Description and type For customizing the description container. Extended from { children?: ReactNode; } & CommonProps & Omit<any, "ref"> & { grow?: boolean | 0 | 5 | 2 | 8 | 3 | 6 | 1 | 4 | 7 | 9 | 10; component?: ElementType; } & { ...; } | Default value |
Prop fieldFlexItemProps# | Description and type For customizing the field container. Extended from { children?: ReactNode; } & CommonProps & Omit<any, "ref"> & { grow?: boolean | 0 | 5 | 2 | 8 | 3 | 6 | 1 | 4 | 7 | 9 | 10; component?: ElementType; } & { ...; } | Default value |