VariableInput

Components/Form

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

Overview

Copy

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

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

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

Copy

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

Rows

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

Copy

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.

Copy

Common use case examples

Manual embed

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

Copy

Automations

Use the variable input to send personalized messages and updates.

Copy

Code

Copy

Props

NameTypeDefaultDescription
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
disabledboolean—Specifies whether input should be disabled or not.
initialValuestring''Defines an initial value to display.
multilinebooleantrueSpecifies 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
placeholderstring—Sets a placeholder message to display.
readOnlyboolean—Specifies whether input is read only.
rowsnumber1Set 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.
spellCheckbooleanfalseSpecifies whether spellcheck is enabled.
status"error" | "warning" | "loading" | "success"—Specify the status of a field.
statusMessageReactNode—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 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 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)
  • 1.256.0 (2026-02-06) — fix: fix Android IME autosuggestion issues (#15908)
  • 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)
  • 1.244.0 (2026-01-02) — fix: new line overlaps existing lines (#15710)
  • 1.244.0 (2026-01-02) — feat: add support for spell check prop (#15725)
  • 1.241.0 (2025-12-17) — feat: add insert text method (#15667)
  • 1.239.0 (2025-12-12) — fix: mobile chrome issue with autocomplete and typing (#15650) — has visual changes
  • 1.237.0 (2025-12-08) — breaking: fix incorrect css specificity (tokens not applied correctly) (#15633)
  • 1.232.0 (2025-11-28) — maintenance release, no component-specific changes
  • 1.216.0 (2025-09-01) — breaking: e3 tokenization (#15243)
  • 1.199.0 (2025-06-13) — feat: add param variableKey to focus public method (#14979)
  • 1.198.0 (2025-06-07) — fix: placeholder wrapping outside of container (#14954)
  • 1.186.0 (2025-05-05) — feat: add focus public method (#14817)
  • 1.145.0 (2024-12-09) — fix: cursor from pointer to text change (#14222)
  • 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

Last updated: 22 October 2026

Did this help?