Components/Form
Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/formfield
Form fields are labels used to tell the user what they need to select or enter in the field of a form. They can indicate if a field is mandatory and can include a tooltip to provide more information.
<Heading/> component instead.A form field consists of label, suffix and children areas. Children areas can include any kind of form element.
Control the label position with the labelPlacement prop. It supports 3 options:
top in all common cases.left to save vertical space in less spacious layouts. This only works well with short labels. When using, be mindful of localization.<ToggleSwitch/>, use right.When the field label is placed on the side, its vertical position can be controlled with the labelAlignment prop. It supports 2 options:
<InputArea/> or <RadioGroup/>, use top.middle for single line inputs.Mark mandatory fields with an asterisk by using required.
To change the status and display an inline message below any component, use the status and statusMessage props.
status prop to error.status prop to warning.status prop to loading.statusMessage prop with no status.Use a tooltip to provide users with more information about the field and what they need to input.
Add a custom element on the top right of the input to provide more options or information. This area accepts any component as a child.
Note: The suffix area replaces the character count; they can’t be used simultaneously.
Define the maximum length of the field value by using the charCount prop. Any value over the allowed character count will not be added.
Control the container width with stretchContent. This property is enabled by default and must be turned off when the form element has a fixed width, like when a <ToggleSwitch/> is used.
Use the ellipsis prop for overflow text. The full text will be displayed in a <Tooltip/> when a user hovers over the button. Control the style of the tooltip using the tooltipProps.
To display label in multiple lines, use maxLines to define how many lines should be visible. maxLines can be used together with ellipsis to control after how many lines label would get truncated.
NOTE: it's not recommended to have labels longer than two lines, as the content would become too text heavy.
Use a top label on forms whenever possible. This creates a clear hierarchy and is the most readable format.
Use a top label or a left label depending on the layout. For example, a left label works best with a single toggle button.
| Name | Type | Default | Description |
|---|---|---|---|
charCount | number | — | Sets the maximum length for the field value. Character count is displayed in the top right corner of a component. |
children | | ReactNode | ((data: { setCharactersLeft: CharactersLeftFn }) => ReactNode) | — | when function, it receives object with: * setCharactersLeft - function accepts a number and will display it on top right of FormField component Note that alternatively you can also use charCount prop to display character count instead of using the render function method. Accept any kind of component as a child element. A child should be a form element like an Input, InputArea, Dropdown or RichTextArea. |
dataHook | string | — | Applies a data-hook HTML attribute that can be used in tests. |
ellipsis | boolean | — | When true, text that is longer than it's container will be truncated to a single line followed by ellipsis. Otherwise the text will break into several lines. |
id | string | — | Input id used for connecting label to the input element using native for attribute js <FormField id="myFormField" label="Hello"> <Input id="myFormField"/> </FormField> |
infoContent | ReactNode | — | Displays a passed info message in a tooltip. Default value is a text string, but it can also be overridden with any other component. |
infoIconAriaLabel | string | — | Sets the accessible label of the infoContent icon trigger. There is no default: pass a translated label that describes what the info is about. |
infoTooltipProps | TooltipCommonProps | — | Allows control over the tooltip style and behaviour by passed tooltip properties. |
inputWidth | string | — | Applies custom width to the child component. Works only when labelPlacement value is right or left |
label | ReactNode | — | Sets a field label. It's default value is a text string, but it can be overridden with any other component. |
labelAlignment | "top" | "middle" | — | Controls the label alignment. |
labelId | string | — | Sets the id of the label. |
labelPlacement | "right" | "left" | "top" | — | Controls the label placement. Forced to top when mobile is enabled on <WixDesignSystemProvider/> — side labels then stack above the field to save horizontal space. |
labelSize | "small" | "tiny" | "medium" | — | Controls the size of label. |
labelWidth | string | — | Applies custom width to the label. Works only when labelPlacement value is right or left |
maxLines | number | — | maxLines truncates text at a specific number of lines. |
required | boolean | — | Marks a field as mandatory with an asterisk (*) at the end of a label. |
showInfoIconOnHover | boolean | false | Controls the visibility of the information icon based on hover. If set to true, the icon appears only when the component is hovered over. By default, the icon is always visible (false). When the component is wrapped with SidePanel.Field, the hover area extends to cover the full bounds of the component. |
status | "error" | "warning" | "loading" | — | Sets the type of status message, to give it appropriate colors and icons. |
statusMessage | ReactNode | — | Sets the status message. It is displayed bellow the child component. |
stretchContent | boolean | true | Specifies whether the content (children container) grows when there's space available. Otherwise, it only uses the necessary space. |
suffix | ReactNode | — | Adds a custom element at the end of the label row (it overrides the charCount in case it's provided). |
Import the driver matching your test environment:
| Method | Description |
|---|---|
element | — |
getChildren | get children |
getLabel | get label |
getLabelSize | returns label size |
isRequired | returns true whether form field is required |
getLengthLeft | returns the length left |
isLengthExceeded | returns whether the form field length is exceeded |
hasTooltip | returns true whether form field has tooltip |
getInfoContent | returns tooltip text of the info content |
getSuffix | get form field suffix |
hoverInfoIcon | hovers over the formfield infoicon |
getStatusMessage | returns status message text |
hasStatus | return true if it has a given status |
exists | Checks whether the component found with the given data hook. |
click | Clicks on the component root element. |
base | Returns UniDriver for the base element. |
infoIconAriaLabel prop to name the infoContent icon for screen readers; pass a translated label. (#17045)WixDesignSystemProvider has mobile enabled. Touch devices can't hover, so showInfoIconOnHover and the compact-mode hover reveal no longer hide it there. Desktop behavior is unchanged. (#17264) — has visual changesLast updated: 22 October 2026