Close menu

Pattern Library

Text Input

Window sizes

Text Input

A single-line text input field. Supports validation states, width modifiers, and input masks. Follows USWDS text input patterns.

Props

Prop Default Description
id Unique ID for the input; also used to link the associated c-label
name Form field name submitted with the form
type HTML input type (e.g., text, email, password, search)
value Pre-filled value for the field
placeholder Placeholder text displayed inside the input when empty
hint Hint text displayed below the label via c-label
error Error message text; also applies the error styling class to the input
success Set to "true" to apply the success styling class to the input
disabled Set to "true" to disable the input
readonly Set to "true" to make the input read-only
required Set to "true" to mark the input as required
width Width modifier: 2xs, xs, sm, md, lg, xl, 2xl
maxlength Maximum number of characters allowed
pattern HTML pattern attribute for client-side validation
inputmode Hints at the type of virtual keyboard to show (e.g., numeric, text)
input_classes Additional CSS classes applied directly to the <input> element
class usa-input Override the base CSS class on the <input> element

Example Usage

Basic Text Input

<c-label id="input-basic" label="Text input label" />
<c-text-input id="input-basic" name="basic" type="text" />

Text Input with Hint

<c-label id="input-hint" label="Text input with hint" hint="This is a helpful hint message." />
<c-text-input id="input-hint" name="hint" type="text" />

Text Input with Error

<c-label id="input-error" label="Text input with error" error="This field is required." />
<c-text-input id="input-error" name="error" type="text" error="This field is required." />

Text Input with Success

<c-label id="input-success" label="Text input with success" />
<c-text-input id="input-success" name="success" type="text" value="Valid input" success="true" />

Small Width Input

<c-label id="input-small" label="Small text input" />
<c-text-input id="input-small" name="small" type="text" width="sm" />

Medium Width Input

<c-label id="input-medium" label="Medium text input" />
<c-text-input id="input-medium" name="medium" type="text" width="md" />

Disabled Input

<c-label id="input-disabled" label="Disabled text input" />
<c-text-input id="input-disabled" name="disabled" type="text" value="This is disabled" disabled="true" />

Readonly Input

<c-label id="input-readonly" label="Readonly text input" />
<c-text-input id="input-readonly" name="readonly" type="text" value="This is readonly" readonly="true" />

Required Input

<c-label id="input-required" label="Required text input" required="true" />
<c-text-input id="input-required" name="required" type="text" required="true" />

Input with Max Length

<c-label id="input-maxlength" label="Text input with max length" hint="Maximum 10 characters." />
<c-text-input id="input-maxlength" name="maxlength" type="text" maxlength="10" />

Social Security Number Input Mask

<c-label id="input-ssn" label="Social Security Number" hint="Format: XXX-XX-XXXX" />
<c-text-input
    id="input-ssn"
    name="ssn"
    type="text"
    placeholder="___-__-____"
    pattern="^(?!(000|666|9))\d{3} (?!00)\d{2} (?!0000)\d{4}$"
    input_classes="usa-masked"
    inputmode="numeric"
/>

US Telephone Number Input Mask

<c-label id="input-tel" label="US Telephone Number" hint="Format: (XXX) XXX-XXXX" />
<c-text-input
    id="input-tel"
    name="tel"
    type="text"
    placeholder="(___) ___-____"
    pattern="^\(\d{3}\) \d{3}-\d{4}$"
    input_classes="usa-masked"
    inputmode="numeric"
/>

9-Digit US ZIP Code Input Mask

<c-label id="input-zip9" label="9-Digit US ZIP Code" hint="Format: XXXXX-XXXX" />
<c-text-input
    id="input-zip9"
    name="zip9"
    type="text"
    placeholder="_____-____"
    pattern="^\d{5}(-\d{4})?$"
    input_classes="usa-masked"
    inputmode="numeric"
/>

Alphanumeric Input Mask

<c-label id="input-alphanumeric" label="Alphanumeric Input" hint="Format: A1A 2B3" />
<c-text-input
    id="input-alphanumeric"
    name="alphanumeric"
    type="text"
    placeholder="___ ___"
    pattern="\w\d\w \d\w\d"
    input_classes="usa-masked"
    inputmode="text"
    data-charset="A# #A#"
/>

Usage Notes

  • Always pair c-text-input with a c-label that references the same id
  • Pass error to both c-label (for the error message display) and c-text-input (for the error CSS class)
  • Width modifiers (width) constrain the visual width of the input without affecting its submitted value
  • Input masks require USWDS JavaScript and the usa-masked class on the input via input_classes
  • Wrap c-label and c-text-input in c-form-group for correct USWDS form layout
{% load cotton %}

<div class="component-variants">
    <h1>Text Input Component</h1>

    {% for variant in variants %}
    <div class="component-variant">
        <h2 class="variant-title">{{ variant.title }}</h2>
        {% cotton label id="{{ variant.id }}" label="{{ variant.label }}" hint="{{ variant.hint }}" error="{{ variant.error }}" required="{{ variant.required }}" %}{% endcotton %}
        {% cotton text_input id="{{ variant.id }}" name="{{ variant.name }}" label="{{ variant.label }}" type="{{ variant.type }}" value="{{ variant.value }}" placeholder="{{ variant.placeholder }}" hint="{{ variant.hint }}" error="{{ variant.error }}" success="{{ variant.success }}" disabled="{{ variant.disabled }}" readonly="{{ variant.readonly }}" required="{{ variant.required }}" width="{{ variant.width }}" maxlength="{{ variant.maxlength }}" pattern="{{ variant.pattern }}" input_classes="{{ variant.input_classes }}" placeholder="{{ variant.placeholder }}" inputmode="{{ variant.inputmode }}" aria-describedby="{{ variant.aria_describedby }}" data-charset="{{ variant.data_charset }}" %}
        {% endcotton %}
    </div>
    {% endfor %}
    
</div>

name: Text Input
context:
  variants:
    - title: "Basic Text Input"
      id: "input-basic"
      name: "basic"
      label: "Text input label"
      type: "text"


    - title: "Text Input with Hint"
      id: "input-hint"
      name: "hint"
      label: "Text input with hint"
      type: "text"
      value: ""
      hint: "This is a helpful hint message"
      error: ""
      success: ""
      disabled: ""
      readonly: ""
      required: ""
      width: ""


    - title: "Text Input with Error"
      id: "input-error"
      name: "error"
      label: "Text input with error"
      type: "text"
      value: ""
      hint: ""
      error: "This field is required"
      success: ""
      disabled: ""
      readonly: ""
      required: ""
      width: ""


    - title: "Text Input with Success"
      id: "input-success"
      name: "success"
      label: "Text input with success"
      type: "text"
      value: "Valid input"
      hint: ""
      error: ""
      success: "true"
      disabled: ""
      readonly: ""
      required: ""
      width: ""


    - title: "Small Width Input"
      id: "input-small"
      name: "small"
      label: "Small text input"
      type: "text"
      value: ""
      hint: ""
      error: ""
      success: ""
      disabled: ""
      readonly: ""
      required: ""
      width: "sm"


    - title: "Medium Width Input"
      id: "input-medium"
      name: "medium"
      label: "Medium text input"
      type: "text"
      value: ""
      hint: ""
      error: ""
      success: ""
      disabled: ""
      readonly: ""
      required: ""
      width: "md"


    - title: "Disabled Input"
      id: "input-disabled"
      name: "disabled"
      label: "Disabled text input"
      type: "text"
      value: "This is disabled"
      hint: ""
      error: ""
      success: ""
      disabled: "true"
      readonly: ""
      required: ""
      width: ""


    - title: "Readonly Input"
      id: "input-readonly"
      name: "readonly"
      label: "Readonly text input"
      type: "text"
      value: "This is readonly"
      hint: ""
      error: ""
      success: ""
      disabled: ""
      readonly: "true"
      required: ""
      width: ""


    - title: "Required Input"
      id: "input-required"
      name: "required"
      label: "Required text input"
      type: "text"
      value: ""
      hint: ""
      error: ""
      success: ""
      disabled: ""
      readonly: ""
      required: "true"
      width: ""


    - title: "Input with Maxlength"
      id: "input-maxlength"
      name: "maxlength"
      label: "Text input with max length"
      type: "text"
      value: ""
      hint: "Maximum 10 characters"
      error: ""
      success: ""
      disabled: ""
      readonly: ""
      required: ""
      width: ""
      maxlength: "10"


    - title: "Social Security Number"
      id: "input-ssn"
      name: "ssn"
      label: "Social Security Number"
      type: "text"
      hint: "Format: XXX-XX-XXXX"
      placeholder: "___-__-____"
      pattern: "^(?!(000|666|9))\\d{3} (?!00)\\d{2} (?!0000)\\d{4}$"
      input_classes: "usa-masked"
      inputmode: "numeric"
      aria-describedby: "ssnHint"


    - title: "US Telephone Number Input Mask"
      id: "input-tel"
      name: "tel"
      label: "US Telephone Number"
      type: "text"
      hint: "Format: (XXX) XXX-XXXX"
      placeholder: "(___) ___-____"
      pattern: "^\\(\\d{3}\\) \\d{3}-\\d{4}$"
      input_classes: "usa-masked"
      inputmode: "numeric"
      aria-describedby: "telHint"

    - title: "9 Digit US ZIP Code Input Mask"
      id: "input-zip9"
      name: "zip9"
      label: "9 Digit US ZIP Code"
      type: "text"
      hint: "Format: XXXXX-XXXX"
      placeholder: "_____-____"
      pattern: "^\\d{5}(-\\d{4})?$"
      input_classes: "usa-masked"
      inputmode: "numeric"
      aria-describedby: "zip9Hint"
  

    - title: "Alphanumeric Input Mask"
      id: "input-alphanumeric"
      name: "alphanumeric"
      label: "Alphanumeric Input"
      type: "text"
      hint: "Format: A1A 2B3"
      placeholder: "___ ___"
      pattern: "\\w\\d\\w \\d\\w\\d"
      input_classes: "usa-masked"
      inputmode: "text"
      aria_describedby: "alphanumericHint"
      data_charset: "A#A #A#"