Text field

A text field is an input field that merchants can type into. It has a range of options and supports several text formats including numbers.

Examples

Use to allow merchants to provide text input when the expected input is short. For longer input, use the auto grow or multiline options.

Drag to resize example

Props

align
"left" | "center" | "right"
Determines the alignment of the text in the input
ariaActiveDescendant
string
Indicates the id of a related component’s visually focused element to the input
ariaAutocomplete
string
Indicates what kind of user input completion suggestions are provided
ariaControls
string
Indicates the id of a component controlled by the input
ariaExpanded
boolean
Indicates whether or not a Popover is displayed
ariaOwns
string
Indicates the id of a component owned by the input
autoCompleteRequired
string
Enable automatic completion by the browser. Set to "off" when you do not want the browser to fill in info
autoFocus
boolean
Automatically focus the input
clearButton
boolean
Show a clear text button in the input
connectedLeft
React.ReactNode
An element connected to the left of the input
connectedRight
React.ReactNode
An element connected to the right of the input
disabled
boolean
Disable the input
error
string | ReactElement | (string | ReactElement)[] | boolean
Error to display beneath the label
focused
boolean
Force the focus state on the input
helpText
React.ReactNode
Additional hint text to display
id
string
ID for the input
inputMode
"none" | "text" | "decimal" | "numeric" | "tel" | "search" | "email" | "url"
Choose the keyboard that should be used on mobile devices
labelRequired
React.ReactNode
Label for the input
labelAction
Action
Adds an action to the label
labelHidden
boolean
Visually hide the label
max
number | string
Mimics the behavior of the native HTML attribute, limiting the maximum value
maxHeight
number | string
Maximum height of the input element. Only applies when `multiline` is `true`
maxLength
number
Maximum character length for an input
min
number | string
Mimics the behavior of the native HTML attribute, limiting the minimum value
minLength
number
Minimum character length for an input
monospaced
boolean
Indicates whether or not a monospaced font should be used
multiline
boolean | number
Allow for multiple lines of input
name
string
Name of the input
pattern
string
A regular expression to check the value against
placeholder
string
Hint text to display
prefix
React.ReactNode
Text to display before value
readOnly
boolean
Disable editing of the input
requiredIndicator
boolean
Visual required indicator, adds an asterisk to label
role
string
Defines a specific role attribute for the input
showCharacterCount
boolean
Indicates whether or not the character count should be displayed
spellCheck
boolean
Indicate whether value should have spelling checked
step
number
Limit increment value for numeric and date-time inputs
suffix
React.ReactNode
Text to display after value
type
"text" | "email" | "number" | "password" | "search" | "tel" | "url" | "date" | "datetime-local" | "month" | "time" | "week" | "currency"
Determine type of input
value
string
Initial value for the input
onBlur
() => void
Callback when focus is removed
onChange
(value: string, id: string) => void
Callback when value is changed
onClearButtonClick
(id: string) => void
Callback when clear button is clicked
onFocus
() => void
Callback when input is focused

Accessibility

Structure

Screen readers convey information about text fields automatically through native HTML.

  • Use the disabled prop to add the HTML disabled attribute to the text field.
  • Use the readOnly prop to add the HTML readonly attribute to the text field.
  • If you use the type prop, then some assistive technologies adapt the software keyboard to the current task. This helps merchants with mobility, vision, and cognitive issues to enter information more easily.

Use the id prop to provide a unique id attribute value for the text field. If you don't provide an id, then the component generates one automatically. All text fields need to have unique id values.

Labeling

The label prop is required to convey the purpose of the checkbox to all merchants.

If there are separate visual cues that convey the purpose of the text field to sighted merchants, then the label can be visually hidden with the labelHidden prop.

When you provide help text via the helpText prop or an inline error message via the error prop, the help or error content is conveyed to screen reader users with the aria-describedby attribute. This attribute causes the content to be read along with the label, either immediately or after a short delay.

Use the placeholder prop to provide additional instructions. However, don’t rely on placeholders alone since the content isn’t always conveyed to all merchants.

Do

  • Use the label to provide instructions critical to using the text field
  • Use help text and placeholder text to provide additional, non-critical instructions

Don’t

Use the placeholder to provide information that’s required to use the text field.

Keyboard support

Text fields have standard keyboard support.

  • Merchants who rely on the keyboard expect to move focus to each text field using the tab key (or shift + tab when tabbing backwards)
  • If the type is set to number, then merchants can use the up and down arrow keys to adjust the value typed into the field
  • Using the disabled prop will prevent the text field from receive keyboard focus or inputs
  • The readOnly prop allows focus on the text field but prevents input or editing
  • The inputMode prop can be used to bring up a relevant keyboard for merchants on mobile; it’s passed down to the input as an inputmode attribute

Automatically focusing

Although you can use the autoFocus prop to automatically move focus to the text field, it’s generally best to avoid focusing on fields automatically. The autoFocus prop is set to false by default and should only be used in cases where it won’t force focus to skip other controls or content of equal or greater importance.

Default text field

Use to allow merchants to provide text input when the expected input is short. For longer input, use the auto grow or multiline options.

Default text field

Number field

Use when input text should be a number.

This will display the right keyboard on mobile devices.

Number text field with numeric keyboard

Email field

Use when the text input should be an email address.

This will display the right keyboard on mobile devices.

Email field with email keyboard

Multiline text field

Use when the expected input could be more than one line. The field will automatically grow to accommodate additional text.

Multi-line text field

Text field with placeholder text

Use to provide a short, non-essential hint about the expected input. Placeholder text is low-contrast, so don’t rely on it for important information.

Default text field with placeholder text hint

Text field with help text

Use to show short instructional content below the text field. Help text works to help merchants understand how to fix errors that result from incorrect formatting (such as dates or passwords with specific character requirements). If more explanation is needed, link to the Shopify Help Center.

Default text field with help text

Text field with prefix or suffix

Use as a special form of help text that works best inline.

  • Use a prefix for things like currency symbols (“$”, “¥”, “£”).
  • Use suffix for things like units of measure (“in”, “cm”).

Default text field with prefix and suffix

Text field with connected fields

Use when a text field and several related fields make up a logical unit.

If inputting weight as a number and a separate unit of measurement, use a text field with a selector (like “kg” or “lb”) as a connected field.

Text field with connected selector

Text field with icon action

Use to let merchants take an action within the text field.

For example, tap on a barcode icon to launch the camera and scan barcode for the barcode field. This helps merchants simplify their input.

Text field with icon action inside the text field

Text field with validation error

Use to let merchants know if their input is valid or if there’s an error. Whenever possible, validate input as soon as merchants have finished interacting with a field (but not before). If a field already has an error, validate and remove errors as merchants type so they can immediately see when an error has been fixed.

Text field with error

Accessibility

See Material Design and development documentation about accessibility for Android:

Default text field

Use to allow merchants to provide text input when the expected input is short. For longer input, use the auto grow or multiline options.

Default text field

Number field

Use when input text should be a number.

This will display the right keyboard on mobile devices.

Number text field with numeric keyboard

Email field

Use when the text input should be an email address.

This will display the right keyboard on mobile devices.

Email field with email keyboard

Multiline text field

Use when the expected input could be more than one line. The field will automatically grow to accommodate additional text.

Multi-line text field

Text field with placeholder text

Use to provide a short, non-essential hint about the expected input. Placeholder text is low-contrast, so don’t rely on it for important information.

Default text field with placeholder text hint

Text field with help text

Use to show short instructional content below the text field. Help text works to help merchants understand how to fix errors that result from incorrect formatting (such as dates or passwords with specific character requirements). If more explanation is needed, link to the Shopify Help Center.

Default text field with help text

Text field with prefix or suffix

Use as a special form of help text that works best inline.

  • Use a prefix for things like currency symbols (“$”, “¥”, “£”).
  • Use suffix for things like units of measure (“in”, “cm”).

Default text field with prefix and suffix

Text field with connected fields

Use when a text field and several related fields make up a logical unit.

If inputting weight as a number and a separate unit of measurement, use a text field with a selector (like “kg” or “lb”) as a connected field.

Text field with connected selector

Text field with icon action

Use to let merchants take an action within the text field.

For example, tap on a barcode icon to launch the camera and scan barcode for the barcode field. This helps merchants simplify their input.

Text field with icon action inside the text field

Text field with validation error

Use to let merchants know if their input is valid or if there’s an error. Whenever possible, validate input as soon as merchants have finished interacting with a field (but not before). If a field already has an error, validate and remove errors as merchants type so they can immediately see when an error has been fixed.

Text field with error

Accessibility

See Apple’s Human Interface Guidelines and API documentation about accessibility for iOS:

Best practices

Text fields should:

  • Be clearly labeled so it’s obvious to merchants what they should enter into the field
  • Be labeled as “Optional” when you need to request input that’s not required
  • Only ask for information that’s really needed
  • Validate input as soon as merchants have finished interacting with a field (but not before)

Autocomplete

The autocomplete attribute in an input field controls two types of browser behavior:

  1. Browser autofill: a feature that automatically populates form fields with previously-saved information, such as passwords, addresses, and credit card data.
  1. Browser autocomplete - a feature that displays previously submitted values for that field.
  • When this is on for a field, a user is presented a list with previously submitted values for the input

Recommendation

Always add an autocomplete attribute and value to inputs if the type is: color, date, datetime-local, email, month, number, password, range, search, tel, text, time, url, or week.

Turning autofill/autocomplete off

Even if you do not want the browser to autofill a user's information, it is recommended you still have an autocomplete attribute with the value off or nope.

Unfortunately, not all browsers support or respect autocomplete="off". This makes things challenging. Chrome, for example, has a long outstanding bug and won't add support for off for now.

Browser Support for autocomplete="off" Details
Chrome Partial Intentionally ignores off value when the user uses the browser's autofill functionality. See bug.
Safari Partial Ignores off value for username, email and password fields.
Firefox Partial Ignores off value for login forms. See bug.
Edge Partial Intentionally ignores off value when the user uses the browser's autofill functionality.

Chrome does seem to turn autocomplete off when using the value nope (or any non valid string). However, we have seen some inconsistencies even with that support.

Recommendation (Chrome only)

  • Turning off both autofill and browser autocomplete (previously submitted values) in Chrome
    • Use autocomplete=nope and also must have a name attribute.
  • Turning off browser autocomplete (previously submitted values) in Chrome
    • If you don't have name attribute and the field is not a typical autofill input (address, email, etc), use autocomplete=off.

Content guidelines

For text field content guidelines, reference the text fields experience page.

Edit source on GitHub