Web components - Text input: Pre-alpha

[amyleadem]

Summary

• Design a markup structure for the light and shadow DOM
• Design component variants, props, parts, slots, and vars

Research and planning tasks

• Gather code samples from the landscape
  • Note: Use the Landscape analysis code samples template to collect relevant code samples from across the landscape
• Identify and document the component’s critical content
  • Document the component content that is critical for end-user understanding. Note: This critical content should always appear on the page, even in non-JS environments.
• Design and document the structure for the light DOM
• Design and document the structure for the shadow DOM
• Design and document the expected component customization methods
  • List and define the proposed component variants
  • List and define props
  • List and define slots
  • List and define CSS Parts
  • List and define CSS Variables
  • List any component content that will need to be translated into other languages

[amyleadem]

Text input web component design plan

Landscape analysis

Text input code samples from the landscape analysis (Google docs 🔒)

Proposed component structure

Critical content

The <input> and <label> elements contain critical content that should always be included on the page, even in non-JS environments. For this reason, users should be expected to add a complete, accessible input component inside of the custom element tags:

Element	Required attributes	Content
<input>	id, name	N/A
<label>	for (Note: The for attribute should match the id of the related input element)	Informational label text

Note

This solution deviates from the implementations we saw across the landscape. Almost universally, the other design systems in our sample pool opted to build a fully prop-driven component. We decided to go a different path so that the page builds a fully functional and accessible component, even when JavaScript fails or is slow.

More information: Conversation about opting for progressive enhancement for text input (Google docs 🔒)

Light DOM

Sample default implementation:

<usa-text-input>
    <label for="input-type-text">Text input label</label>
    <input id="input-type-text" name="input-type-text" />
</usa-text-input>

Sample complex variant implementation:

<usa-text-input state="error" width="lg">
    <label for="input-type-text">Text input label</label>
    <div class="usa-hint" id="inputHint">Hint text</div>
    <input type="tel" id="input-type-text" name="input-type-text" ariadescribedby="inputHint" />
</usa-text-input>

Shadow DOM

Same as USWDS 3

<label for="input-type-text" class="usa-label">Text input label</label>
<input id="input-type-text" name="input-type-text" class="usa-input">

Variants

Current variants

USWDS 3 variant	Web components variant	Description	Defined via
Error state	Error state	Styles for the error state	state prop
Success state	Success state	Styles for the success state	state prop
Disabled state	Disabled state	Styles for the disabled state	state prop
aria-disabled state	aria-disabled state	Styles for the aria-disabled state	state prop
Focused state	Focused state	Styles for the focused state	state prop
Input width	Width	Set the width of the input	width prop

Proposed additional variants

USWDS 3 variant	Web components variant	Description	Defined via
--	Prefix	Add custom text or icon to the input prefix	prefix or prefix-icon prop
--	Suffix	Add custom text or icon to the input suffix	suffix or suffix-icon prop
--	Required	Add indicator that field is required	required prop

Note

Textarea is currently bundled with the text input in USWDS 3. Because its html structure requires the <textarea> tag instead of the <input> tag, I propose that we create a separate custom element for <usa-textarea>.

Note

We could consider including some custom styles for common text input types, like tel, email, etc. I imagine we could add an icon prefix for these types when appropriate. However, this might be too opinionated and we can instead let users choose to add a prefix with the prefix-icon prop.

Props

Current variants

Property	Description	Expected values
state	Sets the state of the component	error, success, disabled, focus (?)
width	Set the width of the input element and label	2xs, xs, sm, small, md, medium, lg, xl, 2xl`

Proposed additional variants

Property	Description	Expected values
prefix	Add content for an input prefix	string
prefix-icon	Add icon for an input prefix	Name of icon
suffix	Add content for an input suffix	string
suffix-icon	Add content for an input suffix	Name of icon
required	Add indicator for required field	boolean

Slots

Unnamed slot

CSS Parts

Part name	Element
input	<input>
label	<label>

CSS Variables

Current settings

USWDS 3 setting	CSS custom property	Description
$theme-input-line-height	--theme-input-line-height	Line-height of input element
$theme-input-max-width	--theme-input-max-width	Max width of the input element
$theme-input-state-border-width	--theme-input-state-border-width	Border width of special state inputs (like error state)

Proposed additional setting

USWDS 3 setting	CSS custom property	Description
--	--theme-input-state-border-negative-margin	Size of the negative margin between the left border and input elements
--	--theme-form-disabled-background-color	The background color of disabled form elements
--	--theme-form-disabled-text-color	The text color of disabled form elements

Translatable content

N/A

[amyleadem]

Next steps

• Make hint a prop or slot or
  • Consider if hints will have rich text or escaped characters
• Convert usa-hint to a <p>
• Add numbers to pre-release template for easier reference
• Consider converting to a markdown PR
• Consider adding open questions/proposals section