> 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: InputWithLabel Component

## Article: InputWithLabel Component

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

## Article Content:

# InputWithLabel

_Components/Form/InputWithLabel_

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

## Overview

```jsx
() => {
  const [value, setValue] = React.useState('Michael Lawrence');

  return (
    <StorybookComponents.Stack flexDirection="column" width="50%">
      <InputWithLabel
        label="Full Name"
        value={value}
        onChange={(e) => setValue(e.target.value)}
      />
    </StorybookComponents.Stack>
  );
};
```

InputWithLabel allows you to insert short text values in a field with a built-in label. It's constructed by wrapping a regular `<Input/>` component with `<LabeledElement/>`.

### Do

- Use it to insert text values in the Wix Premium checkout form.

### Don't

- Don't use it in Wix Business Manager applications, use `<FormField/>` with `<Input/>` instead.

### Feature examples

#### Status

Control component status using \`status\` prop. It supports two states:\
 - \`error\` - use it to highlight an invalid value\
 - \`warning\` - use it to highlight a value that impacts user business or can't be validated\
\
Explain the status with \`statusMessage\` prop.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <InputWithLabel label="Error" status="error" />
  <InputWithLabel
    label="Error with message"
    status="error"
    statusMessage="Message explaining the status"
  />
</StorybookComponents.Stack>;
```

#### Status Message

Explain the status with \`statusMessage\` prop. The message is shown below the field, next to the status icon.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <InputWithLabel
    label="Email"
    value="john@"
    status="error"
    statusMessage="Enter a valid email address"
  />
  <InputWithLabel
    label="Coupon code"
    value="SUMMER"
    status="warning"
    statusMessage="This coupon expires tomorrow"
  />
</StorybookComponents.Stack>;
```

#### Disabled

Disable all input interactions with \`disabled\` prop. Use it to highlight unavailable functions.

```jsx
<InputWithLabel label="Field" value="Disabled" disabled />;
```

#### Suffix

Explain field values with additional information added to the \`suffix\` area. This prop accepts text, icons and even buttons. It accepts an array of objects as well.

```jsx
<StorybookComponents.Stack flexDirection="column" gap="0">
  <InputWithLabel label="One item" suffix={[<Icons.InfoCircle />]} />
  <InputWithLabel
    label="Two items"
    suffix={[<Icons.Hidden />, <Icons.LockLocked />]}
  />
  <InputWithLabel
    label="Three items"
    suffix={[
      <Box>Suffix</Box>,
      <Icons.LockLocked />,
      <Box color="B10">
        <Icons.ExternalLink style={{ cursor: 'pointer' }} />
      </Box>,
    ]}
  />
  <InputWithLabel
    label="Hover icon to see cursor change"
    suffix={[
      <Box color="B10">
        <Icons.InfoCircle style={{ cursor: 'pointer' }} />
      </Box>,
    ]}
  />
</StorybookComponents.Stack>;
```

#### Type

Control an acceptable value format with the \`type\` prop. This component accepts all [native HTML types](https://www.w3schools.com/html/html_form_input_types.asp).

```jsx
<StorybookComponents.Stack flexDirection="column" gap="0">
  <InputWithLabel label="Text" type="text" />
  <InputWithLabel label="Number" type="number" />
  <InputWithLabel label="Password" type="password" />
</StorybookComponents.Stack>;
```

#### Max length

Restrict the number of characters that can be entered into a field with the \`maxLength\` prop.

```jsx
<InputWithLabel
  label="Start typing to see that field accept no more than 5 characters"
  maxLength={5}
/>;
```

#### Bottom line border

Style the component using \`border\` prop. It supports 2 styles:\
 - \`default\` - use in all common cases.\
 - \`bottomLine\` - use as a title which can be edited on the click.

```jsx
<StorybookComponents.Stack flexDirection="column" gap="0">
  <InputWithLabel label="Default" border="standard" />
  <InputWithLabel label="Bottom line" border="bottomLine" />
</StorybookComponents.Stack>;
```

### Common use case examples

#### Checkout form

This input with labels can only be used to build a Premium Checkout form.

```jsx
<Card>
  <Card.Content>
    <Layout>
      <Cell>
        <Text>Card Details</Text>
      </Cell>
      <Cell>
        <InputWithLabel label="Card Number" type="number" maxLength={16} />
      </Cell>
      <Cell span={6}>
        <InputWithLabel label="Expiration" type="number" maxLength={5} />
      </Cell>
      <Cell span={6}>
        <InputWithLabel
          label="CVV"
          type="number"
          maxLength={5}
          suffix={[
            <InfoIcon content="Last 3 digits on the back of your card" />,
          ]}
        />
      </Cell>
    </Layout>
  </Card.Content>
</Card>;
```

## Code

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

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `ariaControls` | `string` | — | Associate a control with the regions that it controls. |
| `ariaDescribedby` | `string` | — | Associate a region with its descriptions. Similar to aria-controls but instead associating descriptions to the region and description identifiers are separated with a space. |
| `ariaLabel` | `string` | — | Define a string that labels the current element in case where a text label isn't visible on the screen. |
| `ariaRoledescription` | `string` | — | Sets the `aria-roledescription` attribute of the `<input>` element, giving assistive technologies a readable description of its role. |
| `autocomplete` | `string` | — | Sets the value of the native `autocomplete` attribute, for example `off` or `email`. |
| `autoFocus` | `boolean` | — | Focus the element on mount (standard React input autoFocus) |
| `autoSelect` | `boolean` | — | Automatically selects the entire input text. |
| `backgroundColor` | `string` | — | Sets the background color of the input. Accepts any CSS color value. |
| `border` | `"standard" \| "bottomLine"` | — | Control the border style of input. |
| `children` | `ReactNode` | — |  |
| `clearButton` | `boolean` | — | Displays clear button (X) on a non-empty input. |
| `clearButtonAriaLabel` | `string` | — | Aria label for the clear button. |
| `clearButtonTooltipContent` | `ReactNode` | — | When provided, hovering displays a tooltip with this content. |
| `clearButtonTooltipProps` | `TooltipCommonProps` | — | Clear button tooltip props. |
| `customInput` | `ReactNode \| Function` | — | Render a custom input instead of the default html input tag. |
| `dataHook` | `string` | — | Applies a data-hook HTML attribute that can be used in the tests. |
| `defaultValue` | `string \| number` | — | Defines the initial value of an input. |
| `disabled` | `boolean` | — | Specifies whether input should be disabled or not. |
| `disableEditing` | `boolean` | — | Restricts input editing. |
| `enterKeyHint` | `"search" \| "enter" \| "done" \| "go" \| "next" \| "previous" \| "send"` | — | Sets the label of the virtual keyboard's enter key on touch devices. |
| `focusOnClearClick` | `boolean` | — | Specifies whether to focus the field when clear button is clicked. |
| `hideStatusSuffix` | `boolean` | — | Specifies whether status suffix should be hidden. |
| `id` | `string` | — | Assigns a unique identifier for the root element. |
| `inputmode` | `string` | — | Sets the value of the native `inputmode` attribute, which tells mobile browsers which on-screen keyboard to show, for example `numeric` or `email`. |
| `inputRef` | `null \| (instance: HTMLInputElement \| null) => void \| RefObject<HTMLInputElement>` | — | Ref to the underlying `<input>` DOM element. Accepts callback and object refs. Use for input masking libraries such as `use-mask-input`. Memoize callback refs to avoid reattaching on every render. |
| `label` | `string` | — | Sets the field label. |
| `max` | `number` | — | Sets a maximum value of an input. Similar to html5 max attribute. |
| `maxLength` | `number` | — | Sets the maximum number of characters that can be inserted to a field. |
| `menuArrow` | `boolean` | — | Specifies whether input should have a dropdown menu arrow on the right side. |
| `min` | `number` | — | Sets a minimum value of an input. Similar to HTML5 min attribute. |
| `name` | `string` | — | Reference element data when a form is submitted. |
| `noLeftBorderRadius` | `boolean` | — | Specifies whether input shouldn't have rounded corners on its left. |
| `noRightBorderRadius` | `boolean` | — | Specifies whether input shouldn't have rounded corners on its right. |
| `onBlur` | `FocusEventHandler` | — | Defines a standard input onBlur callback. |
| `onChange` | `ChangeEventHandler` | — | Defines a standard input onChange callback. |
| `onClear` | `(event: KeyboardEvent<HTMLButtonElement> \| MouseEvent<HTMLButtonElement, MouseEvent>) => void` | — | Displays clear button (X) on a non-empty input and calls a callback function. |
| `onCompositionChange` | `(isComposing: boolean) => void` | — | Defines a callback function called on compositionstart/compositionend events. |
| `onCopy` | `ClipboardEventHandler<HTMLInputElement>` | — | Defines a callback handler that is called when user copies text to a clipboard (using a mouse or keyboard shortcut) |
| `onEnterPressed` | `KeyboardEventHandler<HTMLInputElement>` | — | Defines a callback handler that is called when the user presses -enter-. |
| `onEscapePressed` | `KeyboardEventHandler<HTMLInputElement>` | — | Defines a callback handler that is called when the user presses -escape-. |
| `onFocus` | `FocusEventHandler` | — | Defines a standard input onFocus callback. |
| `onInputClicked` | `MouseEventHandler` | — | Defines a standard input onClick callback. |
| `onKeyDown` | `KeyboardEventHandler<HTMLInputElement>` | — | Defines a standard input onKeyDown callback. |
| `onKeyUp` | `KeyboardEventHandler<HTMLInputElement>` | — | Defines a standard input onKeyUp callback. |
| `onPaste` | `ClipboardEventHandler<HTMLInputElement>` | — | Defines a callback handler that is called when user pastes text from a clipboard (using a mouse or keyboard shortcut) |
| `pattern` | `string` | — | Sets a pattern that typed value must match to be valid (regex) |
| `placeholder` | `string` | — | Sets a placeholder message to display. |
| `prefix` | `ReactNode` | — | Pass a component you want to show as the prefix of the input, e.g., text, icon. |
| `readOnly` | `boolean` | — | Specifies whether input is read only. |
| `ref` | `null \| string \| (instance: InputImperativeActions \| null) => void \| RefObject<InputImperativeActions>` | — | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). |
| `required` | `boolean` | — | Specifies whether input is mandatory. |
| `role` | `string` | — | Specifies the role of the input element for accessibility. |
| `rtl` | `boolean` | — | Specifies text direction. If true, the text is displayed from right to left. |
| `size` | `"small" \| "tiny" \| "medium" \| "large"` | — | Controls the size of the input. Default value: `medium` |
| `status` | `"error" \| "warning" \| "loading"` | — | Specify the status of a field. |
| `statusMessage` | `ReactNode` | — | Defines the message to display on status icon hover. If not given or empty, no tooltip is displayed. |
| `statusMessageTooltipProps` | `TooltipCommonProps` | — | Status message tooltip props. |
| `step` | `number` | — | Specifies the interval between number values. |
| `suffix` | `ReactNode` | — | Pass a component you want to show as the suffix of the input, e.g., text, icon. |
| `tabIndex` | `number` | — | Indicates that element can be focused and where it participates in sequential keyboard navigation. |
| `textOverflow` | `"ellipsis" \| "clip"` | — | Handles text overflow behavior. It can either `clip` (default) or display `ellipsis`. |
| `tooltipPlacement` | `"right" \| "left" \| "top" \| "bottom" \| "auto" \| "auto-start" \| "auto-end" \| "top-start" \| "top-end" \| "right-start" \| "right-end" \| "bottom-end" \| "bottom-start" \| "left-end" \| "left-start"` | — | Controls placement of a status tooltip. |
| `type` | `string` | — | Specifies the type of `<input/>` element to display. Default is text. |
| `value` | `string \| number` | — | Specifies the current value of the element. |
| `withSelection` | `boolean` | — |  |

## Testkit

Import the driver matching your test environment:

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

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

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

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

### Driver methods

| Method | Description |
| --- | --- |
| `getSuffixesCount` | Gets the amount of rendered suffixes |
| `hasErrorMessage` | Returns true if an error status message exists |
| `getErrorMessage` | Gets the error status message |
| `getValue` | — |
| `clickInput` | — |
| `enterText` | — |
| `getLabelText` | — |
| `isCustomInput` | — |
| `isFocusedStyle` | — |
| `getMaxLength` | — |
| `getPlaceholder` | — |
| `exists` | Checks whether the component found with the given data hook. |
| `element` | Gets the component root element. |
| `click` | Clicks on the component root element. |
| `base` | Returns UniDriver for the base element. |

## Changelog

- **1.344.0** (2026-10-28) — 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.336.0** (2026-10-13) — maintenance release, no component-specific changes
- **1.330.3** (2026-09-29) — 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.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.288.0** (2026-06-15) — maintenance release, no component-specific changes
- **1.273.0** (2026-04-30) — 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.254.0** (2026-02-03) — maintenance release, no component-specific changes
- **1.242.0** (2025-12-19) — maintenance release, no component-specific changes
- **1.228.0** (2025-11-18) — maintenance release, no component-specific changes
- **1.147.0** (2024-12-13) — maintenance release, no component-specific changes
- **1.138.1** (2024-10-30) — maintenance release, no component-specific changes
- **1.115.0** (2024-07-17) — maintenance release, no component-specific changes
- **1.112.0** (2024-07-03) — maintenance release, no component-specific changes
- **1.108.0** (2024-06-03) — maintenance release, no component-specific changes
- **1.102.0** (2024-04-16) — maintenance release, no component-specific changes
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes