> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: FormField Component

## Article: FormField Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/form/form-field-component.md

## Article Content:

# FormField

_Components/Form_

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

## Overview

```jsx
<Box align="center">
  <Box width="30%">
    <FormField
      label="API key"
      infoContent="A code used to identify and authenticate an application or user."
      labelPlacement="top"
    >
      <StorybookComponents.Placeholder height="36px" width="300px" />
    </FormField>
  </Box>
</Box>;
```

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.

```jsx
<FormField
  label="Label"
  suffix={
    <StorybookComponents.Placeholder>
      Suffix area
    </StorybookComponents.Placeholder>
  }
>
  <StorybookComponents.Placeholder>
    Any form element
  </StorybookComponents.Placeholder>
</FormField>;
```

#### 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`.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <FormField label="Top" labelPlacement="top">
    <Input />
  </FormField>
  <FormField label="Left" labelPlacement="left">
    <Input />
  </FormField>
  <FormField label="Right" labelPlacement="right" stretchContent={false}>
    <ToggleSwitch checked />
  </FormField>
</StorybookComponents.Stack>;
```

#### 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.

```jsx
<StorybookComponents.Stack>
  <FormField label="Top" labelPlacement="left" labelAlignment="top">
    <InputArea minHeight="90px" />
  </FormField>
  <FormField label="Middle" labelPlacement="left" labelAlignment="middle">
    <Input />
  </FormField>
</StorybookComponents.Stack>;
```

#### Required

Mark mandatory fields with an asterisk by using `required`.

```jsx
<StorybookComponents.Stack>
  <FormField label="Mandatory field" required>
    <Input />
  </FormField>
  <FormField label="Not mandatory field (optional)">
    <Input />
  </FormField>
</StorybookComponents.Stack>;
```

#### 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`.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <FormField
    labelSize="small"
    label="Label"
    status="error"
    statusMessage="This is an error message."
  >
    <Input />
  </FormField>
  <FormField
    labelSize="small"
    label="Label"
    status="warning"
    statusMessage="This is a warning message."
  >
    <Input />
  </FormField>
  <FormField
    labelSize="small"
    label="Label"
    status="loading"
    statusMessage="This is a loading message."
  >
    <Input />
  </FormField>
  <FormField
    labelSize="small"
    label="Label"
    statusMessage="This is helper text."
  >
    <Input />
  </FormField>
</StorybookComponents.Stack>;
```

#### Additional info

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

```jsx
<FormField
  label="Hover over info icon"
  infoContent="This tooltip provides additional info about what the user needs to put in the input field."
>
  <Input />
</FormField>;
```

#### 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.

```jsx
<FormField
  label="Label"
  suffix={
    <TextButton size="small" suffixIcon={<Icons.ExternalLinkSmall />}>
      Go to External Site
    </TextButton>
  }
>
  <InputArea />
</FormField>;
```

#### 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.

```jsx
() => {
  const [charCount, setCharCount] = React.useState(0);
  const [value, setValue] = React.useState('');

  const handleOnChange = (value) => {
    if (value.length <= 20) {
      setValue(value);
      setCharCount(value.length);
    }
  };
  return (
    <FormField label="Enter more than 20 characters" charCount={20 - charCount}>
      <Input
        value={value}
        onChange={(event) => handleOnChange(event.target.value)}
      />
    </FormField>
  );
};
```

#### 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.

```jsx
<FormField
  label="Not stretched content"
  labelPlacement="right"
  stretchContent={false}
>
  <ToggleSwitch checked />
</FormField>;
```

#### 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.

```jsx
<StorybookComponents.Stack>
  <SidePanel width="288px">
    <SidePanel.Field>
      <FormField label="This is an example text that overflows and is shown in tooltip">
        <Input placeholder="Placeholder" />
      </FormField>
    </SidePanel.Field>
  </SidePanel>
  <SidePanel width="288px">
    <SidePanel.Field>
      <FormField
        ellipsis
        maxLines={2}
        label="This is an example text that fits and is shown in two lines"
      >
        <Input placeholder="Placeholder" />
      </FormField>
    </SidePanel.Field>
  </SidePanel>
</StorybookComponents.Stack>;
```

### 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.

```jsx
<Card>
  <Card.Header title="New dish" />
  <Card.Divider />
  <Card.Content>
    <Layout>
      <Cell span={4}>
        <FormField label="Image">
          <ImageViewer width="100%" height="176px" />
        </FormField>
      </Cell>
      <Cell span={8}>
        <Layout gap="24px">
          <Cell span={8}>
            <FormField label="Name">
              <Input value="My New Dish" />
            </FormField>
          </Cell>
          <Cell span={4}>
            <FormField label="Price">
              <Input value="0" prefix={<Input.Affix>$</Input.Affix>} />
            </FormField>
          </Cell>
          <Cell>
            <FormField label="Description">
              <InputArea
                placeholder="Describe your dish in a few sentences."
                resizable
                rows={3}
              />
            </FormField>
          </Cell>
        </Layout>
      </Cell>
      <Cell span={6}>
        <FormField
          label="Dietary preferences"
          infoContent="Choose which dietary preferences your dish is appropriate for."
        >
          <Layout>
            <Cell span={6}>
              <Box direction="vertical" gap="12px">
                <Checkbox>No salt</Checkbox>
                <Checkbox>Vegan</Checkbox>
                <Checkbox>Vegetarian</Checkbox>
              </Box>
            </Cell>
            <Cell span={6}>
              <Box direction="vertical" gap="12px">
                <Checkbox>Gluten free</Checkbox>
                <Checkbox>Organic</Checkbox>
                <Checkbox>Spicy</Checkbox>
              </Box>
            </Cell>
          </Layout>
        </FormField>
      </Cell>
      <Cell span={3}>
        <FormField label="Visibility">
          <Checkbox checked>Visible on site</Checkbox>
        </FormField>
      </Cell>
      <Cell span={3}>
        <FormField label="Availability">
          <Checkbox checked>In stock</Checkbox>
        </FormField>
      </Cell>
    </Layout>
  </Card.Content>
</Card>;
```

#### 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.

```jsx
() => {
  const [selectedOption, setSelectedOption] = React.useState(0);
  const [value, setValue] = React.useState(2);
  const [toggleChecked, setToggleChecked] = React.useState(true);

  const options = [
    { id: 0, value: 'Image' },
    { id: 1, value: 'Video' },
    { id: 2, value: 'Image and video' },
    { id: 3, value: 'Document' },
    { id: 4, value: 'Audio' },
  ];
  return (
    <SidePanel maxHeight="576px" width="288px" skin="floating">
      <SidePanel.Header title="Upload Settings" />
      <SidePanel.Content noPadding>
        <SidePanel.Field>
          <FormField label="Supported file type">
            <Dropdown
              placeholder="Select"
              size="small"
              options={options}
              onSelect={(option) => setSelectedOption(Number(option.id))}
              selectedId={selectedOption}
            />
          </FormField>
        </SidePanel.Field>
        <SidePanel.Field>
          <FieldSet
            gap="small"
            legend="Max number of files"
            columns="auto 60px"
          >
            <Slider
              onChange={(newValue) => setValue(Number(newValue))}
              min={0}
              max={10}
              value={value}
              displayMarks={false}
            />
            <Input
              size="small"
              value={value}
              onChange={(e) => setValue(Number(e.target.value))}
            />
          </FieldSet>
        </SidePanel.Field>
        <SidePanel.Field>
          <FormField label="Is required" labelPlacement="left" labelWidth="1fr">
            <ToggleSwitch
              size="small"
              checked={toggleChecked}
              onChange={() => setToggleChecked(!toggleChecked)}
            />
          </FormField>
        </SidePanel.Field>
        <SidePanel.Section title="Display settings">
          <SidePanel.Field>
            <FormField label="Field title">
              <Input size="small" placeholder="Enter field title" />
            </FormField>
          </SidePanel.Field>
          <SidePanel.Field>
            <FormField label="Button text">
              <Input size="small" value="Choose file" />
            </FormField>
          </SidePanel.Field>
        </SidePanel.Section>
      </SidePanel.Content>
    </SidePanel>
  );
};
```

## Code

```jsx
import { FormField } from '@wix/design-system';
```

### Props

| 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). |

## Testkit

Import the driver matching your test environment:

```jsx
// UniDriver
import { FormFieldUniDriver } from '@wix/design-system/dist/testkit/unidriver';

// Vanilla
import { FormFieldTestkit } from '@wix/design-system/dist/testkit';

// Puppeteer
import { FormFieldTestkit } from '@wix/design-system/dist/testkit/puppeteer';

// Testing Library
import { FormFieldTestkit } from '@wix/design-system/dist/testkit/testing-library';
```

### Driver methods

| 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. |

## 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](invalid-url))
- **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](invalid-url)) — 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](invalid-url))
- **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](invalid-url))
- **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](invalid-url))
- **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](invalid-url))
- **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](invalid-url))
- **1.172.0** (2025-03-20) — feat: info icon in FormField show on hover on SidePanel.Field ([#14576](invalid-url))
- **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](invalid-url))
- **1.165.0** (2025-02-27) — maintenance release, no component-specific changes
- **1.154.0** (2025-01-16) — fix: handle suffix ([#14459](invalid-url))
- **1.147.0** (2024-12-13) — feat: change suffix alignment ([#14375](invalid-url))
- **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](invalid-url))
- **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](invalid-url))
- **1.102.0** (2024-04-16) — maintenance release, no component-specific changes
- **1.101.0** (2024-04-12) — fix: fix side label overflow ([#13583](invalid-url))
- **1.101.0** (2024-04-12) — feat: support custom label & input widths ([#13595](invalid-url))
- **1.100.0** (2024-04-04) — feat: support top multiline label ([#13535](invalid-url))
- **1.98.0** (2024-03-15) — maintenance release, no component-specific changes
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes