Text field (web component)

<bolt-textfield 
  label="Default text field"
></bolt-textfield>

<bolt-textfield 
  instructionaltext="Use this format: MM/DD/YYYY" 
  label="Date of birth"
></bolt-textfield>

<bolt-textfield 
  label="First name" 
  required 
  error="This field is required"
></bolt-textfield>

<bolt-textfield 
  label="Field name" 
  required 
  invalid
></bolt-textfield>

<bolt-textfield 
  label="Disabled text field" 
  disabled
></bolt-textfield>

<bolt-textfield 
  iconalt="Submit Search" 
  iconname="search" 
  label="Search" 
  optionaltext="hide"
></bolt-textfield>

<bolt-textfield 
  label="Username" 
  indicator="waiting" 
></bolt-textfield>

<bolt-textfield 
  label="Email text field" 
  type="email"
></bolt-textfield>

When using a prefix or suffix, we recommend including a descriptive arialabel to provide context for assistive technology users.

<bolt-textfield 
  label="Donation amount" 
  arialabel="Donation amount in whole dollars" 
  value="20" 
  inputmode="numeric" 
  prefixsymbol="$" 
  suffix=".00" 
  aligninput="right"
></bolt-textfield>

<bolt-textfield 
  label="Non-required text field" 
  optionaltext="hide"
></bolt-textfield>

<bolt-textfield label="Default text field">
  <bolt-contextual-help 
    slot="help" 
    heading="Help text heading"
  >
    <p>Help text body content</p>
  </bolt-contextual-help>
</bolt-textfield>

maxlength controls the number of characters that may be entered, while inputsize sets the width of the input box in terms of average character widths.

<bolt-textfield 
  label="Zip code" 
  maxlength="5"
></bolt-textfield>

<bolt-textfield 
  label="Zip code" 
  inputsize="8"
></bolt-textfield>

The <bolt-textfield> custom element creates a text field with a label and optional instructional and error text:

<bolt-textfield label="First name" error="This field is required" required></bolt-textfield>

The <bolt-textfield> custom element must include one of these three parameters:

• label: The label text for the input.
• arialabel: Sets the aria-label attribute of the underlying <input> element.
  • arialabel should be included when using prefix/prefixsymbol/suffix/suffixsymbol, to clearly describe the type of data to enter.
• arialabelledby: Sets the aria-labelledby attribute of the underlying <input> element.

Additionally, the <bolt-textfield> custom element supports the following parameters:

• value: optional. The initial or set value for the input.
• instructionaltext: optional. The instructional text to display below the input. This should be used to give users additional information about the expected content in the field.
• disabled: optional. If present, disables rendered interactive elements.
• error: optional. The error message to display after the input.
  • Should not be used when component is disabled.
  • For slotted field error see text field error slot
• required: optional. If present, the field is required. Fields that are not required will show "(optional)".
• optionaltext: optional. show (default) or hide. Use to remove the "(optional)" text from non-required fields.
• type: optional. Defaults to text. Any supported HTML text field input type.
  • issue: When setting type="number", Angular users will need to coerce the ngModel value into a number using Number(). Angular users may wish to use the HTML pattern instead of the web component in order to get the full native input number capability.
  • showarrows: optional. If present, displays spin arrows for type="number", by default arrows are hidden.
• maxlength: optional. Maximum allowed input length.
• inputsize : optional. Sets the width of the input box in terms of average character widths. Prefix and suffix, if present, will be in addition to this width. If not specified, the input box will span the full width of its container.
• iconname: optional. The reference name for the attached icon button.
• indicator: optional. error, info, question, success, warning, or waiting. Displays a status indicator on the right side of the textfield.
• iconalt: optional. The alt text for the attached icon button.
• prefix: optional. Text displayed before the text input. Generally, this will be multiple characters.
• prefixsymbol: optional. Text displayed before the text input and stylized as a symbol. Generally, this will be a single character, e.g. "$"
• suffix: optional. Text displayed after the text input. Generally, this will be multiple characters, e.g. ".00".
• suffixsymbol: optional. Text displayed after the input and stylized as a symbol. Generally, this will be a single character, e.g. "%"
• aligninput: optional, left (default) or right. Alignment of the text in the field.
• invalid: optional. If present, the field appears invalid.
• datatestinput optional property to configure the data-test value on the underlying <input> element. Default is input.
• datatestbutton optional property to configure the data-test value on the underlying <button> element. Default is button.

The <bolt-textfield> custom element supports the use of <bolt-contextual-help> via the help slot placeholder. For more information and to see other options visit the contextual help page.

The following attributes are passed through to the native <input> element. Please see the MDN Input element documentation for details.

• spellcheck: optional. Defaults to false.
• autocomplete: optional. Defaults to on. Please see possible values.
• autocorrect: optional. Defaults to off.
• autocapitalize: optional. Defaults to on.
• inputmode: optional. See standard behavior
• pattern: optional. See standard behavior
• min: optional. Defines the minimum value that is acceptable and valid for the input containing the attribute. Should only be used with the number type.
• max: optional. Defines the maximum value that is acceptable and valid for the input containing the attribute. Should only be used with the number type.
• step: optional. The step attribute is a number that specifies the granularity that the value must adhere to. Should only be used with the number type.

The <bolt-textfield> custom element emits the following events:

• bolt-icon-click: emitted when the attached icon button is clicked.

To attach an icon button to the text field, use the iconname and iconalt attributes. Listen for the bolt-icon-click event to handle when a user clicks the icon button attached to a text field.

<bolt-textfield iconalt="Submit Search" iconname="search" label="Search" required></bolt-textfield>

• [data-test="input"] targets primary <input> element

  • Configurable via the datatestinput property

• [data-test="button"] targets <button>for icon-button element

  • Configurable via the datatestbutton property

• A Text field should always be paired with a field label to communicate expected input. Don't remove the label, as it creates accessibility and usability issues.
  • A field label is not needed when the component is used inside a table cell if the column header and table are coded to provide appropriate accessibility, and by extension context for the Text field.
• The first letter entered in a Text field should automatically be capitalized, except when asking for a username, password, and/or email address.
• Allow users to enter formatted numbers (e.g., telephone number, Social Security number) inside a single Text field to ensure accessibility for visually impaired users.
• Use "type" to differentiate virtual keyboards on mobile devices (e.g., number, tel, text, range, url, etc.). This helps to optimize input of frequently used characters inside that Text field.
  • Common text field types that require optimized virtual keyboards for entering numbers, text or mixed formats include:
    • Number (such as phone number, credit card number or PIN)
    • Text (such as name, username or URL)
    • Mixed format (such as email address, street address or search query)
• Use confirm (re-type) fields for collecting information such as an email address, account number, routing numbers or password. The time and effort it can take a user or company to correct this information later can be significant. Entering this information twice on a form takes a fraction of that time and effort.
• Include a static prefix or suffix in Text fields for entering units like dollars or percentages.
• Allow users to show and hide the characters entered into security-sensitive text fields for passwords, credit card numbers, Social Security numbers, etc.
• Use the instructional text below a Text field to display its valid input format.
• Use Contextual help in conjunction with the field label to provide answers to common questions about expected field input.
• Avoid pre-populating a Text field.
• Text field should not be both in error and disabled states at the same time. While this might be technically possible, from a user standpoint, these should be mutually exclusive.
• Avoid enforcing rigid formatting rules; consider potential data variations or masking to account for formatting.
• Input validation and error messaging should, depending on the context of use, occur after users either:
  • submit a form (form-level validation).
  • enter one or more characters (delayed onInput, mid-form validation).
  • exit the field (onBlur, frontend validation only).
• It is generally advised to stack Text fields (and other input fields) when multiple fields are on a screen. This is so fields don't move out of sight for those who have higher levels of zoom set in their browsers.
  • Some exceptions may be with city and state Text fields, middle initial fields, and in equations where field widths are defined by the number of digits allowed.

• When users need to enter a number of characters that easily fits within the width of a typical text field.

• When entering large amounts of text, avoid using Text field, use Text area instead.
• When users need to select multiple values, avoid using Text field, use Checkbox instead.
• Avoid using Text field for entering dates and times, with the exception of entering a birthdate. Use Date picker or a date/time picker.

• Text field labels, instructional text and error messages use sentence case.
• Instructional text should clarify the format of valid user input.
• Error messages should be clear and concise, including a period.

• It is important for form field labels to always remain visible, to help users understand what they're working with. Placeholder text, or text inside the form field, should not be used as a label because it disappears when the user starts typing. This can be confusing, especially for people with cognitive disabilities who might forget what the field is for. It's also a problem for those who use speech-to-text tools because it makes it hard to understand what to say to activate the field.

All Bolt components have gone through accessibility testing, but please keep our accessibility guidelines in mind.