FormField

Components/Form

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/formfield

Overview

Copy

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.

Do

  • Use it to add a label to the field to tell the user what info they need to enter or select.
  • Mark required fields as mandatory.
  • Provide additional information about the form element in a tooltip.

Don't

  • Don’t use it as a title for sections or groups of elements. Use the appropriate <Heading/> component instead.

Feature examples

Structure

A form field consists of label, suffix and children areas. Children areas can include any kind of form element.

Copy

Label placement

Control the label position with the labelPlacement prop. It supports 3 options:

  • Use top in all common cases.
  • Use left to save vertical space in less spacious layouts. This only works well with short labels. When using, be mindful of localization.
  • For <ToggleSwitch/>, use right.
Copy

Label alignment

When the field label is placed on the side, its vertical position can be controlled with the labelAlignment prop. It supports 2 options:

  • For larger form elements like <InputArea/> or <RadioGroup/>, use top.
  • Use middle for single line inputs.
Copy

Required

Mark mandatory fields with an asterisk by using required.

Copy

Status and message

To change the status and display an inline message below any component, use the status and statusMessage props.

  • For error messages, set the status prop to error.
  • For warning messages, set the status prop to warning.
  • For loading messages, set the status prop to loading.
  • To show helper text, use the statusMessage prop with no status.
Copy

Additional info

Use a tooltip to provide users with more information about the field and what they need to input.

Copy

Suffix

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.

Copy

Character count

Define the maximum length of the field value by using the charCount prop. Any value over the allowed character count will not be added.

Copy

Stretch content

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.

Copy

Text overflow

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.

Copy

Common use case examples

Regular form

Use a top label on forms whenever possible. This creates a clear hierarchy and is the most readable format.

Copy

Settings panel

Use a top label or a left label depending on the layout. For example, a left label works best with a single toggle button.

Copy

Code

Copy

Props

NameTypeDefaultDescription
charCountnumber—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.
dataHookstring—Applies a data-hook HTML attribute that can be used in tests.
ellipsisboolean—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.
idstring—Input id used for connecting label to the input element using native for attribute js <FormField id="myFormField" label="Hello"> <Input id="myFormField"/> </FormField>
infoContentReactNode—Displays a passed info message in a tooltip. Default value is a text string, but it can also be overridden with any other component.
infoIconAriaLabelstring—Sets the accessible label of the infoContent icon trigger. There is no default: pass a translated label that describes what the info is about.
infoTooltipPropsTooltipCommonProps—Allows control over the tooltip style and behaviour by passed tooltip properties.
inputWidthstring—Applies custom width to the child component. Works only when labelPlacement value is right or left
labelReactNode—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.
labelIdstring—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.
labelWidthstring—Applies custom width to the label. Works only when labelPlacement value is right or left
maxLinesnumber—maxLines truncates text at a specific number of lines.
requiredboolean—Marks a field as mandatory with an asterisk (*) at the end of a label.
showInfoIconOnHoverbooleanfalseControls 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.
statusMessageReactNode—Sets the status message. It is displayed bellow the child component.
stretchContentbooleantrueSpecifies whether the content (children container) grows when there's space available. Otherwise, it only uses the necessary space.
suffixReactNode—Adds a custom element at the end of the label row (it overrides the charCount in case it's provided).

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
element—
getChildrenget children
getLabelget label
getLabelSizereturns label size
isRequiredreturns true whether form field is required
getLengthLeftreturns the length left
isLengthExceededreturns whether the form field length is exceeded
hasTooltipreturns true whether form field has tooltip
getInfoContentreturns tooltip text of the info content
getSuffixget form field suffix
hoverInfoIconhovers over the formfield infoicon
getStatusMessagereturns status message text
hasStatusreturn true if it has a given status
existsChecks whether the component found with the given data hook.
clickClicks on the component root element.
baseReturns UniDriver for the base element.

Changelog

  • 1.340.0 (2026-10-21) — maintenance release, no component-specific changes
  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.335.0 (2026-10-12) — maintenance release, no component-specific changes
  • 1.331.0 (2026-10-01) — feat: add an infoIconAriaLabel prop to name the infoContent icon for screen readers; pass a translated label. (#17045)
  • 1.330.3 (2026-09-29) — fix: the info icon is now always visible when 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 changes
  • 1.330.0 (2026-09-28) — maintenance release, no component-specific changes
  • 1.329.0 (2026-09-24) — maintenance release, no component-specific changes
  • 1.328.0 (2026-09-22) — maintenance release, no component-specific changes
  • 1.325.0 (2026-09-17) — maintenance release, no component-specific changes
  • 1.320.1 (2026-09-04) — maintenance release, no component-specific changes
  • 1.317.0 (2026-08-26) — maintenance release, no component-specific changes
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.291.0 (2026-06-19) — maintenance release, no component-specific changes
  • 1.289.0 (2026-06-17) — fix: compactMode didn't affect infoIcon visibility (#16360)
  • 1.288.0 (2026-06-15) — maintenance release, no component-specific changes
  • 1.278.0 (2026-05-08) — maintenance release, no component-specific changes
  • 1.273.0 (2026-04-30) — maintenance release, no component-specific changes
  • 1.271.0 (2026-04-22) — maintenance release, no component-specific changes
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.257.0 (2026-02-19) — feat: add medium label size (#15932)
  • 1.254.0 (2026-02-03) — maintenance release, no component-specific changes
  • 1.251.0 (2026-01-28) — breaking: info icon border clips and alignment (#15870)
  • 1.247.2 (2026-01-21) — maintenance release, no component-specific changes
  • 1.242.0 (2025-12-19) — maintenance release, no component-specific changes
  • 1.241.0 (2025-12-17) — maintenance release, no component-specific changes
  • 1.221.1 (2025-10-16) — fix: status icon alignment to start (#15418)
  • 1.213.0 (2025-08-19) — maintenance release, no component-specific changes
  • 1.181.0 (2025-04-18) — fix: compactMode now based on classname instead of context (#14743)
  • 1.172.0 (2025-03-20) — feat: info icon in FormField show on hover on SidePanel.Field (#14576)
  • 1.170.0 (2025-03-12) — maintenance release, no component-specific changes
  • 1.169.0 (2025-03-10) — maintenance release, no component-specific changes
  • 1.168.0 (2025-03-07) — breaking: left & right status align (#14587)
  • 1.165.0 (2025-02-27) — maintenance release, no component-specific changes
  • 1.154.0 (2025-01-16) — fix: handle suffix (#14459)
  • 1.147.0 (2024-12-13) — feat: change suffix alignment (#14375)
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.129.0 (2024-09-25) — maintenance release, no component-specific changes
  • 1.126.0 (2024-09-09) — breaking: alignment adjustments (#14096)
  • 1.116.0 (2024-07-22) — maintenance release, no component-specific changes
  • 1.114.0 (2024-07-11) — maintenance release, no component-specific changes
  • 1.109.2 (2024-06-17) — maintenance release, no component-specific changes
  • 1.107.0 (2024-05-29) — fix: fix label size specificity (#13789)
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 1.101.0 (2024-04-12) — fix: fix side label overflow (#13583)
  • 1.101.0 (2024-04-12) — feat: support custom label & input widths (#13595)
  • 1.100.0 (2024-04-04) — feat: support top multiline label (#13535)
  • 1.98.0 (2024-03-15) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 22 October 2026

Did this help?