sp-textfield

Examples

API

Attributes and Properties #

Property	Attribute	Type	Default	Description
`allowedKeys`	`allowed-keys`	`string`	`''`
`autocomplete`	`autocomplete`	`\| HTMLInputElement['autocomplete'] \| HTMLTextAreaElement['autocomplete'] \| undefined`
`autofocus`	`autofocus`	`boolean`	`false`	When this control is rendered, focus it automatically
`dir`	`dir`	`'ltr' \| 'rtl'`	`'ltr'`
`disabled`	`disabled`	`boolean`	`false`	Disable this control. It will not receive focus or events
`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`
`tabIndex`	`tabIndex`	`number`		The tab index to apply to this control. See general documentation about the tabindex HTML property
`_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 #

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>

Spectrum Web Components