FieldSet

Components/Form

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

Overview

Copy

A field set wraps a group of related components in a form, has a title (legend), and can include a tooltip for extra information.

Do

  • Use it to provide a short title for a group of related form components.
  • Use it to give a group title for screen reader users.
  • Provide additional information about the group in a tooltip.

Don't

  • Don't use it to add a label for an individual form component. Use <FormField/> instead.

Feature examples

Structure

A field set consists of legend, suffix and children areas.

Children and suffix areas can include any actions or form components.

Copy

Legend placement

Control the legend position with the legendPlacement. It supports 4 options:

  • For all common cases use top (default).
  • Use left or right to save vertical space in less spacious layouts. This only works well with short legends. When using, be mindful of localization.
  • Use none to visually hide the legend. It will still be available for screen readers.
Copy

Legend alignment

When legend is placed on the side, its vertical position can be controlled with legendAlignment. It supports 2 options:

  • For all common cases use top (default).
  • Use middle for single line inputs.
Copy

Required

Mark mandatory field sets with an asterisk by using required.

Copy

Status and message

To change the status and display a message below the field set, use status and statusMessage.

  • For an error message, set the status to error.
  • For a warning message, set the status to warning.
  • To show helper text, use the statusMessage with no status.

Note: to set the status and message for individual child components, use the same props within that component's FormField.

Copy

Additional info

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

To add info icon content use infoContent.

Copy

Suffix

Add a custom element in the top-right corner of the field set to add extra actions or information. Any component can be used in this area.

Or use charCount to show how many characters are left in a text input.

Note: Choose either charCount or a custom element inside suffix; using both together is not possible.

Copy

Content direction

Choose how child components are arranged in the field set:

  • horizontal (default) arranges them in a row.
  • vertical arranges them in a column.
Copy

Content alignment

Choose how child components are aligned using alignment.

In horizontal:

  • start (default) aligns to the top.
  • center aligns to the middle.
  • end to aligns to the bottom.

In vertical:

  • start (default) aligns to the left.
  • center aligns to the center.
  • end to aligns to the right.
Copy

Content width

Use columns to control the width of each field set child component. Check developer examples for more guidelines.

Note: columns only works with horizontal direction.

Copy

Gap

Control the space between field set child components with gap:

  • For all common cases use small (default).
  • Use medium in more spacious layouts.
  • Use large for extra space between components.
Copy

Developer examples

Custom content width

Set the width of each child component using columns.

  • Use min-content to make the child component as narrow as possible.
  • Use auto to make the child component fill in all available space.
  • Use px to set the component's width.
  • Use fr to set the column proportions. For example, use 1fr 1fr for equal width child components and 1fr 3fr to make the first child fill 25% and second to fill 75% of available width.
  • Use a combination of all 4 values to create custom content layouts.

Note: Do not use percentage values as they will cause child components to exceed the field set width.

Copy

Common use case examples

In setting panels

Use field sets to group related form components together and give them a title.

When individual component labels are descriptive enough, set field set legendPlacement to none.

Copy

Accessibility examples

Using hidden legends

Provide extra information within the legend for screen reader users.

To hide this information on screen, set the legendPlacement to none.

Copy

Status messages

When using FieldSet with FormField, the status message is connected to Input element automatically. If it's a FieldSet message without status, it applies to all Inputs under that FieldSet and if message has a status, it only applies the message to the FormField of matching status.

If more control is required over status message linking, set FieldSet statusId and Input aria-describedby to the same value. This disables the automatic linking.

Copy

Code

Copy

Props

NameTypeDefaultDescription
alignment"center" | "end" | "start"—Controls the alignment of all field set child components.
charCountnumber—Sets the maximum length for the field value inside field set child input. Character count is displayed in the top right corner of a component.
children (required)ReactNode—Accepts any kind of components as child elements. A child component should be a form element like an Input, InputArea, Dropdown or RichTextArea.
columnsstring—Controls the width of each field set child component. Works only with horizontal direction.
dataHookstring—Applies a data-hook HTML attribute to be used in the tests.
direction"horizontal" | "vertical"—Controls if field set child components are rendered horizontally or vertically.
ellipsisboolean—Truncates legend that is longer than its parent container and displays ellipsis at the end of the last line. Enabled by default legend placement is set to top.
gap"small" | "medium" | "large"—Controls the gap between all field set child components.
infoContentReactNode—Displays a passed info message in a tooltip next to field set legend. Default value is a text string, but it can also be overridden with any other component.
infoTooltipPropsTooltipCommonProps—Allows control over the tooltip style and behaviour by passed tooltip properties.
legend (required)ReactNode—Sets a field set legend, which is a descriptive title for a group of components. Its default value is a text string, but it can be overridden with any other component.
legendAlignment"top" | "middle"—Controls the vertical alignment of the legend.
legendPlacement"none" | "right" | "left" | "top"—Controls the position of the legend, in terms of field set child components.
legendSize"small" | "tiny"—Controls the size of the legend.
maxLinesnumber1Truncates legend text at a specific number of lines when using ellipsis.
requiredboolean—Marks the field set as mandatory with an asterisk (*) at the end of the legend.
status"error" | "warning"—Sets the type (color, icon) of a status message for the whole field set.
statusIdstring—Adds an id to a field set status message. Use with aria-describedby attribute on specific input to connect it with FieldSet status message for accessibility.
statusMessageReactNode—Sets the field set status message. It is displayed bellow all field set child components.
suffixReactNode—Adds a custom element at the end of the legend row (it overrides the charCount in case it's provided).

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
getLegendTextget legend text
getLegendSizereturns legend size
getLegendPlacementreturns legend placement
getLegendAlignmentreturns legend alignment
isRequiredreturns true whether field set is required
getCharCountreturns the length left
isLengthExceededreturns whether the field set length is exceeded
getInfoContentreturns tooltip text of the info content
getAlignment—
getDirection—
getGap—
getStatusMessagereturns status message text
hasStatusreturn true if it has a given status
existsChecks whether the component found with the given data hook.
elementGets the component root element.
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.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.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.295.0 (2026-07-03) — 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.272.0 (2026-04-27) — 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.242.0 (2025-12-19) — maintenance release, no component-specific changes
  • 1.225.0 (2025-11-07) — fix: change small gap value (#15455)
  • 1.213.0 (2025-08-19) — maintenance release, no component-specific changes
  • 1.172.0 (2025-03-20) — maintenance release, no component-specific changes
  • 1.170.0 (2025-03-12) — maintenance release, no component-specific changes
  • 1.165.0 (2025-02-27) — maintenance release, no component-specific changes
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.103.3 (2024-04-30) — maintenance release, no component-specific changes
  • 1.102.0 (2024-04-16) — feat: support side multiline legend (#13615)
  • 1.102.0 (2024-04-16) — feat: support multiline legend for top placement (#13603)
  • 1.100.0 (2024-04-04) — maintenance release, no component-specific changes
  • 1.98.0 (2024-03-15) — feat: automatic status message linking to input (#13461)
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 22 October 2026

Did this help?