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

## Article: VariableInput Component

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

## Article Content:

# VariableInput

_Components/Form_

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

## Overview

```jsx
<Box align="center">
  <Box direction="vertical" width="50%">
    <FormField
      label="Welcome message"
      infoContent="A generic message that will be sent out to all new users."
    >
      <VariableInput
        rows={3}
        initialValue="Welcome to Wix, {{list.newUsers}}. We are extremely happy you're joining us and wish you best of luck! "
        variableParser={(value) => (value === 'list.newUsers' ? 'Name' : false)}
      />
    </FormField>
  </Box>
</Box>;
```

Variable input allows you to display `<Tag/>` components in between plain text. Each tag represents a known variable. Input recognizes predefined text strings and matches them with an assigned variable when input loses focus (on blur).

### Do

- Use it to automatically generate a message or a value that includes one or multiple dynamic values.

### Don't

- Don't use it to add multiple new values as tags. Use `<Multiselect/>` with manual input feature instead.

### Feature examples

#### Size

Adjust the component size using the `size` prop. It supports 3 sizes:

- `large` - use when the input needs emphasis.
- `medium` (default) - use for all common cases.
- `small` - use in dense and narrow layouts.

```jsx
() => {
  const variableParser = (key) => {
    const variables = {
      firstName: 'First name',
      city: 'City',
    };

    return variables[key] || false;
  };

  const sizes = ['large', 'medium', 'small'] as const;

  return (
    <>
      {sizes.map((size) => (
        <FormField
          key={size}
          label={size.charAt(0).toUpperCase() + size.slice(1)}
        >
          <VariableInput
            size={size}
            initialValue="{{firstName}} from {{city}}"
            placeholder="Type text and variables like {{firstName}}"
            variableParser={variableParser}
          />
        </FormField>
      ))}
    </>
  );
};
```

#### Status

Control the component status using the `status` prop. It supports 3 states:

- `error` - use to highlight an invalid input.
- `warning` - use to highlight inputs that impact users or can't be validated.
- `loading` - use to show that the value is being uploaded to the server.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <VariableInput
    initialValue="{{status}} is error"
    variableParser={(value) => (value === 'status' ? 'Status' : false)}
    status="error"
  />
  <VariableInput
    initialValue="{{status}} is warning"
    variableParser={(value) => (value === 'status' ? 'Status' : false)}
    status="warning"
  />
  <VariableInput
    initialValue="{{status}} is loading"
    variableParser={(value) => (value === 'status' ? 'Status' : false)}
    status="loading"
  />
</StorybookComponents.Stack>;
```

#### Status message

Add text that explains the status or what action the user should take with the `statusMessage` prop.

Showing the status message inline, directly below the input is preferred in all default cases.

- To add an accessible inline message, wrap the component in a `<FormField/>` and add the `statusMessage`.
- To add a status message in a tooltip that requires users to hover on the icon, use the `statusMessage` prop.

View more inline status message examples in `<FormField/>`.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <StorybookComponents.Stack flexDirection="column" gap="12px">
    <Text secondary>For all default cases:</Text>
    <FormField status="error" statusMessage="This is an error message.">
      <VariableInput
        initialValue="See message {{below}}"
        variableParser={(value) => (value === 'below' ? 'below' : false)}
      />
    </FormField>
  </StorybookComponents.Stack>
  <StorybookComponents.Stack flexDirection="column" gap="12px">
    <Text secondary>For narrow layouts only:</Text>
    <VariableInput
      initialValue="{{hover}} on status icon"
      variableParser={(value) => (value === 'hover' ? 'Hover' : false)}
      status="error"
      statusMessage="This is an error message."
    />
  </StorybookComponents.Stack>
</StorybookComponents.Stack>;
```

#### Read-only and disabled

Control input interaction with:

- `readOnly` - disables writing new values, but allows to copy the current value.
- `disabled` - disables all input interactions. Use to highlight unavailable functions.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <VariableInput
    initialValue="{{interactions}} are read only"
    variableParser={(value) =>
      value === 'interactions' ? 'Interactions' : false
    }
    readOnly
  />
  <VariableInput
    initialValue="{{interactions}} are disabled"
    variableParser={(value) =>
      value === 'interactions' ? 'Interactions' : false
    }
    disabled
  />
</StorybookComponents.Stack>;
```

#### Rows

Set the height of a component to fit a specified number of text lines with `rows` prop.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <VariableInput
    rows={1}
    initialValue="Example with 1 {{rows}}"
    variableParser={(value) => (value === 'rows' ? 'row' : false)}
  />
  <VariableInput
    rows={5}
    initialValue="Example with 5 {{rows}}"
    variableParser={(value) => (value === 'rows' ? 'rows' : false)}
  />
</StorybookComponents.Stack>;
```

#### Multiline

Control content scroll direction with the `multiline` prop.

Multiline is allowed by default. Disabling it results in content scrolling horizontally inside of an input.

```jsx
<StorybookComponents.Stack>
  <StorybookComponents.Stack width="50%">
    <VariableInput
      initialValue="Field that have {{multiline}} enabled scroll content vertically"
      multiline={true}
      variableParser={(value) => (value === 'multiline' ? 'multiline' : false)}
    />
  </StorybookComponents.Stack>
  <StorybookComponents.Stack width="50%">
    <VariableInput
      initialValue="Field that have {{multiline}} disabled scroll content horizontally"
      multiline={false}
      variableParser={(value) => (value === 'multiline' ? 'multiline' : false)}
    />
  </StorybookComponents.Stack>
</StorybookComponents.Stack>;
```

### Common use case examples

#### Manual embed

Use a button outside of an input to allow user to embed variables from a predefined list manually.

```jsx
() => {
  const bodyRef = React.useRef(null);
  const variables = [
    {
      key: 'event.date',
      value: 'Event date',
    },
    {
      key: 'last.name',
      value: 'Guest last name',
    },
    {
      key: 'first.name',
      value: 'Guest first name',
    },
    {
      key: 'event.location',
      value: 'Event location',
    },
    {
      key: 'event.name',
      value: 'Event name',
    },
  ];

  const insertVariable = (variable) =>
    bodyRef.current.insertVariable(variable.key);

  return (
    <Box gap="10px">
      <VariableInput
        placeholder="Pick variables and/ or enter strings..."
        variableParser={(value) => {
          const variable = variables.find((item) => item.key === value);

          return variable ? variable.value : false;
        }}
        ref={bodyRef}
        rows={3}
      />
      <PopoverMenu triggerElement={<TextButton>Insert Variable</TextButton>}>
        {variables.map((variable) => (
          <PopoverMenu.MenuItem
            text={variable.value}
            onClick={() => insertVariable(variable)}
          />
        ))}
      </PopoverMenu>
    </Box>
  );
};
```

#### Automations

Use the variable input to send personalized messages and updates.

```jsx
() => {
  const [selectedAction, setSelectedAction] = React.useState(1);

  return (
    <Card>
      <Card.Header
        title="Action"
        subtitle="Do this: send a message"
      ></Card.Header>
      <Card.Divider></Card.Divider>
      <Card.Content>
        <Layout>
          <Cell>
            <Layout gap="12px">
              <Cell span={4}>
                <Thumbnail
                  selected={selectedAction === 1}
                  onClick={() => setSelectedAction(1)}
                  title="Send a chat message"
                  size="small"
                />
              </Cell>
              <Cell span={4}>
                <Thumbnail
                  selected={selectedAction === 2}
                  onClick={() => setSelectedAction(2)}
                  title="Get notified by email"
                  size="small"
                />
              </Cell>
              <Cell span={4}>
                <Thumbnail
                  selected={selectedAction === 3}
                  onClick={() => setSelectedAction(3)}
                  title="Send email to contacts"
                  size="small"
                />
              </Cell>
            </Layout>
          </Cell>

          <Cell>
            <FormField label="Message" required>
              <VariableInput
                rows={5}
                initialValue="Hey {{user.name}}! Thanks for reaching out. We'll be right with you."
                variableParser={(value) =>
                  value === 'user.name' ? 'Name' : false
                }
              />
            </FormField>
          </Cell>
        </Layout>
      </Card.Content>
    </Card>
  );
};
```

## Code

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

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `dataHook` | `string` | — | Applies a data-hook HTML attribute that can be used in the tests. |
| `disabled` | `boolean` | — | Specifies whether input should be disabled or not. |
| `initialValue` | `string` | `''` | Defines an initial value to display. |
| `multiline` | `boolean` | `true` | Specifies whether component allow multiple lines or not. If false, text doesn't wrap and a horizontal scroll appears inside the component. |
| `onBlur` | `(value: string) => void` | — | Defines a callback function that is called on focus out: `onBlur(value: String): void` |
| `onChange` | `(value: string) => void` | — | Defines a callback function that is called each time value is changed: `onChange(value: String): void` |
| `onFocus` | `(value: string) => void` | — | Defines a callback function that is called on focus in: `onFocus(value: String): void` |
| `onSubmit` | `(value: string) => void` | — | Defines a callback function that is called on value submit, in other words after `insertVariable()` and `setValue()` and `insertText()` `onSubmit(value: String): void` |
| `placeholder` | `string` | — | Sets a placeholder message to display. |
| `readOnly` | `boolean` | — | Specifies whether input is read only. |
| `rows` | `number` | `1` | Set the height of a component to fit the given number of rows. |
| `size` | `"small" \| "tiny" \| "medium" \| "large"` | — | Controls the size of the input and variable tags. |
| `spellCheck` | `boolean` | `false` | Specifies whether spellcheck is enabled. |
| `status` | `"error" \| "warning" \| "loading" \| "success"` | — | 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. |
| `variableParser` | `(value: string) => string \| boolean` | — | Defines the variable keys that the component parses and converts to <Tag/> components on blur and while using `insertVariable`. For each key, `variableParser` is called and should return a proper text for that key or false in case the key is invalid. `variableParser(key: String): String\|boolean` |
| `variableTagPropsParser` | `(value: string) => Partial<TagProps>` | — | A function callback that is being called on each keyboard enter and expects a return of object with properties meant for Tag component. It is designed to dynamically determine the styling or properties applied to variable tags within the input field.` |
| `variableTemplate` | `{ prefix: string; suffix: string; }` | — | Defines a template for variable recognition. Typed text strings with matching prefix and suffix symbols are converted to <Tag/> components. |

## Testkit

No testkit for this component — it doesn't expose a unidriver testkit.

## 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.3** (2026-09-29) — maintenance release, no component-specific changes
- **1.330.1** (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.326.0** (2026-09-17) — maintenance release, no component-specific changes
- **1.325.0** (2026-09-17) — maintenance release, no component-specific changes
- **1.323.0** (2026-09-10) — 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.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) — fix: place cursor at end on keyboard focus ([#15998](invalid-url))
- **1.256.0** (2026-02-06) — fix: fix Android IME autosuggestion issues ([#15908](invalid-url))
- **1.250.0** (2026-01-27) — maintenance release, no component-specific changes
- **1.247.2** (2026-01-21) — fix: iOS predictive text concatenating strings ([#15788](invalid-url))
- **1.244.0** (2026-01-02) — fix: new line overlaps existing lines ([#15710](invalid-url))
- **1.244.0** (2026-01-02) — feat: add support for spell check prop ([#15725](invalid-url))
- **1.241.0** (2025-12-17) — feat: add insert text method ([#15667](invalid-url))
- **1.239.0** (2025-12-12) — fix: mobile chrome issue with autocomplete and typing ([#15650](invalid-url)) — has visual changes
- **1.237.0** (2025-12-08) — breaking: fix incorrect css specificity (tokens not applied correctly) ([#15633](invalid-url))
- **1.232.0** (2025-11-28) — maintenance release, no component-specific changes
- **1.216.0** (2025-09-01) — breaking: e3 tokenization ([#15243](invalid-url))
- **1.199.0** (2025-06-13) — feat: add param `variableKey` to `focus` public method ([#14979](invalid-url))
- **1.198.0** (2025-06-07) — fix: placeholder wrapping outside of container ([#14954](invalid-url))
- **1.186.0** (2025-05-05) — feat: add `focus` public method ([#14817](invalid-url))
- **1.145.0** (2024-12-09) — fix: cursor from pointer to text change ([#14222](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.116.0** (2024-07-22) — maintenance release, no component-specific changes
- **1.115.0** (2024-07-17) — 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