sp-textfield

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
_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';

Example #

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

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>
<sp-textfield
id="name-1"
placeholder="Enter your name"
valid
value="My Name"
>
</sp-textfield>

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>
<sp-textfield
id="tel-1"
type="tel"
placeholder="Enter your phone number"
>
</sp-textfield>
<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>
<sp-help-text slot="negative-help-text">Please be "Positive".</sp-help-text>
</sp-textfield>
Managed from above
<sp-field-label for="managed">Stay "Positive"</sp-field-label>
<sp-textfield
id="managed"
pattern="[P][o][s][i][t][i][v][e]"
value="Positive"
oninput='
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>
<sp-help-text slot="help-text">Please be "Positive".</sp-help-text>
</sp-textfield>