Examples API

Attributes and Properties #

Property Attribute Type Default Description allowedKeys allowed-keys string '' autocomplete autocomplete | HTMLInputElement['autocomplete'] | HTMLTextAreaElement['autocomplete'] | undefined focused focused boolean false grows grows boolean false invalid invalid boolean false label label string '' maxlength maxlength number -1 minlength minlength number -1 multiline multiline boolean false pattern pattern string | undefined placeholder placeholder string '' quiet quiet boolean false readonly readonly boolean false required required boolean false rows rows number -1 _type type TextfieldType 'text' valid valid boolean false value value string | number

Slots #

Name Description help-text default or non-negative help text to associate to your form element negative-help-text negative help text to associate to your form element when `invalid`

Events #

Name Type Description change Event An alteration to the value of the element has been committed by the user. input Event The value of the element has changed.

Description #

sp-textfield components are text boxes that allow users to input custom text entries with a keyboard. Various decorations can be displayed around the field to communicate the entry requirements.

Usage #

See it on NPM! How big is this package in your project? Try it on webcomponents.dev

yarn add @spectrum-web-components/textfield

Import the side effectful registration of <sp-textfield> via:

import '@spectrum-web-components/textfield/sp-textfield.js';

When looking to leverage the Textfield base class as a type and/or for extension purposes, do so via:

import { Textfield } from '@spectrum-web-components/textfield';

Sizes #

<sp-field-label size="s" for="name-0-s">Name</sp-field-label>
placeholder="Enter your name"
<sp-field-label for="name-0-m">Name</sp-field-label>
<sp-textfield id="name-0-m" placeholder="Enter your name"></sp-textfield>
<sp-field-label size="l" for="name-0-l">Name</sp-field-label>
placeholder="Enter your name"
Extra Large
<sp-field-label size="xl" for="name-0-xl">Name</sp-field-label>
placeholder="Enter your name"

Variants #

Valid #

Dictate the validity state of the text entry with the valid attribute.

<sp-field-label for="name-1" required>Name</sp-field-label>
placeholder="Enter your name"
value="My Name"

Invalid #

Dictate the invalidity state of the text entry with the invalid attribute.

<sp-field-label for="name-2" required>Name</sp-field-label>
<sp-textfield id="name-2" invalid placeholder="Enter your name"></sp-textfield>

Quiet #

The quiet style works best when a clear layout (vertical stack, table, grid) assists in a user's ability to parse the element. Too many quiet components in a small space can be hard to read.

<sp-field-label for="name-3">Name (quietly)</sp-field-label>
<sp-textfield id="name-3" placeholder="Enter your name" quiet></sp-textfield>

Types #

When inputting URLs, telephone numbers, email addresses, or passwords, specify a type to provide user affordances like mobile keyboards and obscured characters:

  • url
  • tel
  • email
  • password
  • text (default)
<sp-field-label for="tel-1">Telephone</sp-field-label>
placeholder="Enter your phone number"
<sp-field-label for="password-1">Password</sp-field-label>
<sp-textfield id="password-1" type="password"></sp-textfield>

If the type attribute is not specified, or if it does not match any of these values, the default type adopted is "text."

Help text #

Help text can be accessibly associated with an <sp-textfield> element by using the help-text or negative-help-text slots. When using the negative-help-text slot, <sp-textfield> will self manage the presence of this content based on the value of the invalid property on your <sp-textfield> element. Content within the help-text slot will be show by default. When your <sp-textfield> should receive help text based on state outside of the complexity of invalid or not, manage the content addressed to the help-text from above to ensure that it displays the right messaging and possesses the right variant.

Self managed
<sp-field-label for="self">Stay "Positive"</sp-field-label>
<sp-textfield id="self" pattern="[P][o][s][i][t][i][v][e]" value="Positive">
<sp-help-text slot="help-text">
Tell us how you are feeling today.
<sp-help-text slot="negative-help-text">Please be "Positive".</sp-help-text>
Managed from above
<sp-field-label for="managed">Stay "Positive"</sp-field-label>
const helpText = this.querySelector(`[slot="help-text"]`);
helpText.textContent = this.invalid ? `Please be "Positive".` : `Tell us how you are feeling today.`;
helpText.variant = this.invalid ? `negative` : `neutral`;


<sp-help-text slot="neutral-text">
Tell us how you're feeling today.
<sp-help-text slot="help-text">Please be "Positive".</sp-help-text>