Skip to content Shopify logoPolaris

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.

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

import{TextField}from'@shopify/polaris';import{useState,useCallback}from'react';functionTextFieldExample(){const[value,setValue]=useState('Jaded Pixel');consthandleChange=useCallback((newValue:string)=>setValue(newValue),[],);return(<TextFieldlabel="Store name"value={value}onChange={handleChange}autoComplete="off"/>);}

Props

Want to help make this feature better? Pleaseshare your feedback.

This component defines its props in a way that our website can't automatically parse. The type definition is shown below, but it might be hard to read.

type TextFieldProps
&(||)&(|)

Best practices

Text fields should:

  • Be clearly labeled so it’s obvious to merchants what they should enter into the field
  • 被贴上“可选的”当你需要请求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 aninputfield 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

即使你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 supportor respect autocomplete="off". This makes things challenging. Chrome, for example,has a long outstanding bugand won't add support for off for now.

Browser Support forautocomplete="off" Details
Chrome Partial Intentionally ignoresoffvalue when the user uses the browser's autofill functionality.See bug.
Safari Partial Ignoresoffvalue forusername,emailandpasswordfields.
Firefox Partial Ignoresoffvalue for login forms.See bug.
Edge Partial Intentionally ignoresoffvalue 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 bothautofillandbrowser autocomplete(previously submitted values) in Chrome
    • Useautocomplete=nopeand alsomust have anameattribute.
  • Turning offbrowser autocomplete(previously submitted values) in Chrome
    • If you don't havenameattribute and the field is not a typical autofill input (address, email, etc), useautocomplete=off.

Virtual keyboard

Examples of different number keyboards set with inputMode

TheinputModeproperty should be set to select the appropriate virtual keyboard for the type of data expected to be entered by the user. Above are examples of different number keyboards set withinputMode.

Content guidelines

For text field content guidelines, reference thetext fields experience页面。

Accessibility

Structure

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

  • Use thedisabledprop to add the HTMLdisabledattribute to the text field.
  • Use thereadOnlyprop to add the HTMLreadonlyattribute to the text field.
  • If you use thetypeprop, 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 theidprop to provide a uniqueidattribute value for the text field. If you don't provide anid, then the component generates one automatically. All text fields need to have uniqueidvalues.

Labeling

Thelabelprop 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 thelabelHiddenprop.

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

Use theplaceholderprop 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 thetabkey (orshift+tabwhen tabbing backwards)
  • If thetypeis set tonumber, then merchants can use the up and down arrow keys to adjust the value typed into the field when hovering over or focusing the field to make the arrows appear
  • Using thedisabledprop will prevent the text field from receive keyboard focus or inputs
  • ThereadOnlyprop allows focus on the text field but prevents input or editing
  • TheinputModeprop can be used to bring up a relevant keyboard for merchants on mobile; it’s passed down to the input as aninputmodeattribute

Automatically focusing

Although you can use theautoFocusprop to automatically move focus to the text field, it’s generally best to avoid focusing on fields automatically. TheautoFocusprop is set tofalseby 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.