Input

Components/Form

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

Overview

Copy

Inputs let users enter short values into a text field. It can be used for forms and tables, or to build other form components like <AutoComplete/> or <NumberInput/>.

Do

  • Use it to insert names, titles, addresses, and other areas where users will enter short bits of text.
  • Use it to build custom input fields.

Don't

  • Don't use it to insert long paragraphs. Use the <InputArea/> component instead.
  • Don't use it as a search input. Use the <Search/> component instead.

Feature examples

Size

Adjust the size of the input using the size prop. It supports 3 sizes:

  • For most common cases, use the default medium.
  • To emphasize specific inputs in onboarding flows, use large.
  • Use small for more compact layout.
  • Rely of tiny size for very compact layouts, use this size sparingly.
Copy

Border

Style the input using the border prop. It supports 4 styles:

  • For forms and most common cases, use standard.
  • To build inputs that can be used to filter data, use round.
  • Use bottomLine to create an editable, underlined title field.
  • When a component provides its own hover and focus styles, such as a table or spreadsheet cells, use none.
Copy

Status

Control the status of the input using the status prop. It supports 3 states:

  • error demonstrates that a required input is missing something or the entry was invalid.
  • warning highlights an input value that might have a significant impact to a user.
  • loading shows when an input 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. Control tooltip placement with tooltipPlacement prop.

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

Copy

Read-only and disabled

Inputs can also be made read-only or disabled entirely.

  • readOnly disables adding or editing, but allows the user to copy the current value. Use it to display URLs, code, etc.
  • disabledremoves all interactions and creates a disabled input state. Use it to highlight functions that are unavailable.
Copy

Prefix & suffix

Add text, icons or a button at the beginning or end of a text field using prefix and suffix.

Copy

Clear button

Enable a button that lets users easily clear the input value by using the clearButton prop.

Copy

Text overflow

Control long text values with the textOverflow prop. There are 2 options:

  • clip (the default) cuts off text that is longer than the input field.
  • ellipsis truncates the additional text with an ellipsis. This is especially useful with the bottomLine input style.
Copy

Text direction

rtl controls the text direction and layout behavior of the Input.

  • {false} (default): renders input in LTR mode.
  • {true} renders input in RTL mode
Copy

On-stage input color

Since updating Business Manager to use Harmony theme, there has been added a new input background color. You can change it using backgroundColor property.

Important: this is only applicable to Harmony theme, on-stage color is always fixed to --wds-input-background-fill-on-stage

Copy

Developer examples

Masked Input using use-mask-input

Requires use of external package. In this example use-mask-input package is used.

Copy

Masked Input using react-imask

Requires use of external package. In this example react-imask package is used.

Copy

Common use case examples

Compound input

When multiple inputs represent the same kinds of data, like phone numbers or addresses, fields can be shown together under a single title using the <Layout/> component.

Copy

Input as a title

Inputs can also be used as card titles to help organize groups and files. This works best with the bottomLine border.

Copy

Code

Copy

Props

NameTypeDefaultDescription
ariaControlsstring—Associate a control with the regions that it controls.
ariaDescribedbystring—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.
ariaLabelstring—Define a string that labels the current element in case where a text label isn't visible on the screen.
ariaRoledescriptionstring—Sets the aria-roledescription attribute of the <input> element, giving assistive technologies a readable description of its role.
autocompletestring—Sets the value of the native autocomplete attribute, for example off or email.
autoFocusboolean—Focus the element on mount (standard React input autoFocus)
autoSelectboolean—Automatically selects the entire input text.
backgroundColorstring—Sets the background color of the input. Accepts any CSS color value.
border"none" | "standard" | "round" | "bottomLine"—Control the border style of input.
childrenReactNode—
clearButtonboolean—Displays clear button (X) on a non-empty input.
clearButtonAriaLabelstring—Aria label for the clear button.
clearButtonTooltipContentReactNode—When provided, hovering displays a tooltip with this content.
clearButtonTooltipPropsTooltipCommonProps—Clear button tooltip props.
customInputReactNode | Function—Render a custom input instead of the default html input tag.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
defaultValuestring | number—Defines the initial value of an input.
disabledboolean—Specifies whether input should be disabled or not.
disableEditingboolean—Restricts input editing.
enterKeyHint"search" | "enter" | "done" | "go" | "next" | "previous" | "send"—Sets the label of the virtual keyboard's enter key on touch devices.
focusOnClearClickboolean—Specifies whether to focus the field when clear button is clicked.
hideStatusSuffixboolean—Specifies whether status suffix should be hidden.
idstring—Assigns a unique identifier for the root element.
inputmodestring—Sets the value of the native inputmode attribute, which tells mobile browsers which on-screen keyboard to show, for example numeric or email.
inputRefnull | (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.
maxnumber—Sets a maximum value of an input. Similar to html5 max attribute.
maxLengthnumber—Sets the maximum number of characters that can be inserted to a field.
menuArrowboolean—Specifies whether input should have a dropdown menu arrow on the right side.
minnumber—Sets a minimum value of an input. Similar to HTML5 min attribute.
namestring—Reference element data when a form is submitted.
noLeftBorderRadiusboolean—Specifies whether input shouldn't have rounded corners on its left.
noRightBorderRadiusboolean—Specifies whether input shouldn't have rounded corners on its right.
onBlurFocusEventHandler—Defines a standard input onBlur callback.
onChangeChangeEventHandler—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.
onCopyClipboardEventHandler<HTMLInputElement>—Defines a callback handler that is called when user copies text to a clipboard (using a mouse or keyboard shortcut)
onEnterPressedKeyboardEventHandler<HTMLInputElement>—Defines a callback handler that is called when the user presses -enter-.
onEscapePressedKeyboardEventHandler<HTMLInputElement>—Defines a callback handler that is called when the user presses -escape-.
onFocusFocusEventHandler—Defines a standard input onFocus callback.
onInputClickedMouseEventHandler—Defines a standard input onClick callback.
onKeyDownKeyboardEventHandler<HTMLInputElement>—Defines a standard input onKeyDown callback.
onKeyUpKeyboardEventHandler<HTMLInputElement>—Defines a standard input onKeyUp callback.
onPasteClipboardEventHandler<HTMLInputElement>—Defines a callback handler that is called when user pastes text from a clipboard (using a mouse or keyboard shortcut)
patternstring—Sets a pattern that typed value must match to be valid (regex)
placeholderstring—Sets a placeholder message to display.
prefixReactNode—Pass a component you want to show as the prefix of the input, e.g., text, icon.
readOnlyboolean—Specifies whether input is read only.
refnull | 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).
requiredboolean—Specifies whether input is mandatory.
rolestring—Specifies the role of the input element for accessibility.
rtlboolean—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.
statusMessageReactNode—Defines the message to display on status icon hover. If not given or empty, no tooltip is displayed.
statusMessageTooltipPropsTooltipCommonProps—Status message tooltip props.
stepnumber—Specifies the interval between number values.
suffixReactNode—Pass a component you want to show as the suffix of the input, e.g., text, icon.
tabIndexnumber—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.
typestring—Specifies the type of <input/> element to display. Default is text.
valuestring | number—Specifies the current value of the element.
withSelectionboolean—

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
click—
getInputAttribute—
getInputElementClasses—
suffixComponentExists—
getRootElementClasses—
getAriaDescribedby—
getAriaLabel—
getName—
getMaxLength—
getType—
getAriaControls—
clickIconAffix—
clickCustomAffix—
getCustomAffixText—
hasSuffix—
getClearButtonTooltipContent—
prefixComponentExists—
hasPrefix—
hasClearButton—
clickClear—
getValue—
getText—
getPattern—
getPlaceholder—
isOfSize—
getSize—
isDisabled—
isHoveredStyle—
isFocusedStyle—
getRequired—
enterText—
getAutocomplete—
getDefaultValue—
getTabIndex—
isCustomInput—
getReadOnly—
getDisabled—
getTextOverflow—
focus—
blur—
keyUp—
keyDown—
pressKey—
paste—
copy—
wheel—
trigger—
isFocus—
clickMenuArrow—
hasMenuArrow—
isRTL—
getCursorLocation—
clearText—
clickOutside—
isMasked—
isSelected—
hasStatusReturn true if there's a status
getStatusMessageIf there's a status message, returns its text value
existsChecks whether the component found with the given data hook.
elementGets the component root element.
baseReturns UniDriver for the base element.

Changelog

  • 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) — fix: the ticker up/down arrows follow the icon theme, so Harmony (odeditor) shows its own chevrons. (#17155)
  • 1.331.0 (2026-10-01) — maintenance release, no component-specific changes
  • 1.330.3 (2026-09-29) — maintenance release, no component-specific changes
  • 1.330.1 (2026-09-28) — fix: the inputmode prop now reaches the input, so NumberInput shows the numeric keyboard on mobile. GoogleAddressInput without a value now keeps typed text and shows address suggestions. (#17261)
  • 1.330.0 (2026-09-28) — 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.320.1 (2026-09-04) — fix: restore the pre-restyle read-only appearance (grey fill, visible border, full-contrast value, undimmed FormField label) in consumers that load no design-token theme, such as the old Business Manager theme. Every token theme is untouched: the read-only rules resolve through the same theme tokens the default state already uses, so only the token-less fallbacks change. (#16957) — has visual changes
  • 1.317.0 (2026-08-26) — fix: in Harmony (odeditor), read-only inputs no longer show a hover fill and their value text renders muted, and a FormField label above a read-only or disabled Input renders in the disabled color. (#16858) — has visual changes
  • 1.312.0 (2026-08-14) — 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) — fix: clear button no longer opens the dropdown options (#16421)
  • 1.289.0 (2026-06-17) — maintenance release, no component-specific changes
  • 1.288.0 (2026-06-15) — maintenance release, no component-specific changes
  • 1.279.0 (2026-05-13) — maintenance release, no component-specific changes
  • 1.278.0 (2026-05-08) — maintenance release, no component-specific changes
  • 1.277.0 (2026-05-07) — maintenance release, no component-specific changes
  • 1.273.0 (2026-04-30) — 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.263.0 (2026-03-31) — 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.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.232.0 (2025-11-28) — maintenance release, no component-specific changes
  • 1.228.0 (2025-11-18) — fix: use tokens for autofilled state (#15520)
  • 1.224.0 (2025-10-30) — maintenance release, no component-specific changes
  • 1.220.2 (2025-10-06) — fix: stop using specific UniDrivers to not force consumers to install transitional deps (#15385)
  • 1.220.0 (2025-09-29) — maintenance release, no component-specific changes
  • 1.217.0 (2025-09-08) — breaking: remove background and border when border is none or bottomLine (#15284)
  • 1.214.2 (2025-08-25) — maintenance release, no component-specific changes
  • 1.213.0 (2025-08-19) — maintenance release, no component-specific changes
  • 1.212.0 (2025-08-11) — maintenance release, no component-specific changes
  • 1.209.0 (2025-07-30) — fix: isDisabled driver testkit method (#15140)
  • 1.208.0 (2025-07-25) — maintenance release, no component-specific changes
  • 1.207.0 (2025-07-24) — maintenance release, no component-specific changes
  • 1.204.1 (2025-07-10) — maintenance release, no component-specific changes
  • 1.202.0 (2025-06-27) — maintenance release, no component-specific changes
  • 1.200.0 (2025-06-17) — feat: expose input DOM node via imperative handle (#14936)
  • 1.188.1 (2025-05-14) — maintenance release, no component-specific changes
  • 1.184.0 (2025-04-30) — maintenance release, no component-specific changes
  • 1.175.1 (2025-04-01) — maintenance release, no component-specific changes
  • 1.172.1 (2025-03-21) — maintenance release, no component-specific changes
  • 1.167.0 (2025-03-05) — breaking: change menu Arrow Icon color in studio theme (#14579)
  • 1.165.0 (2025-02-27) — feat: expose onCopy (#14563)
  • 1.155.0 (2025-01-23) — maintenance release, no component-specific changes
  • 1.149.1 (2024-12-20) — fix: fix attribute based testkit methods (#14412)
  • 1.149.1 (2024-12-20) — fix: fix testkit disabled flagging (#14413)
  • 1.149.1 (2024-12-20) — fix: revert to previous autoSelect and autoFocus behavior (#14406)
  • 1.147.0 (2024-12-13) — maintenance release, no component-specific changes
  • 1.139.2 (2024-11-12) — maintenance release, no component-specific changes
  • 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.128.0 (2024-09-19) — maintenance release, no component-specific changes
  • 1.127.1 (2024-09-16) — maintenance release, no component-specific changes
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.114.0 (2024-07-11) — feat: expose status message tooltip props (#13917)
  • 1.109.2 (2024-06-17) — maintenance release, no component-specific changes
  • 1.107.0 (2024-05-29) — maintenance release, no component-specific changes
  • 1.106.0 (2024-05-24) — maintenance release, no component-specific changes
  • 1.104.1 (2024-05-14) — fix: fix clear button misalignment (#13717)
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 1.97.2 (2024-03-04) — feat: inputAffix testkit bug fix & Input testkit new method (#13415)
  • 1.97.0 (2024-02-26) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 26 October 2026

Did this help?