Text input

Text inputs are used for inputting single line text data.

Examples#

Base#

Label
<div class="chi-form__item">
  <chi-label for="example__base">Label</chi-label>
  <chi-text-input id="example__base"></chi-text-input>
</div>
<div class="chi-form__item">
  <label class="chi-label" for="example__base">Label</label>
  <input type="text" class="chi-input" id="example__base">
</div>

Disabled#

Use the disabled boolean attribute to prevent users from interacting with an input. Disabled inputs are not submitted with the form and can not receive any browsing events such as mouse clicks or focus. Note: The required attribute can not be used on inputs with a disabled attribute specified.

Label
<div class="chi-form__item">
  <chi-label for="example__disabled">Label</chi-label>
  <chi-text-input id="example__disabled" value="Sample Text" disabled></chi-text-input>
</div>
<div class="chi-form__item">
  <label class="chi-label" for="example__disabled">Label</label>
  <input type="text" class="chi-input" id="example__disabled" value="Sample Text" disabled>
</div>

Readonly#

Use the readonly boolean attribute to prevent users from changing an input value. Unlike disabled inputs, readonly inputs are submitted with the form and can still receive browsing events such as mouse clicks and focus. Note: The required attribute can not be used on inputs with a readonly attribute specified.

Label
<div class="chi-form__item">
  <chi-label for="example__readonly">Label</chi-label>
  <chi-text-input id="example__readonly" value="Sample Text" readonly></chi-text-input>
</div>
<div class="chi-form__item">
  <label class="chi-label" for="example__readonly">Label</label>
  <input type="text" class="chi-input" id="example__readonly" value="Sample Text" readonly>
</div>

Placeholder#

Use the placeholder attribute to provide users with an example of the type of data that can be entered into an input. Note: Placeholder text is not persistent and visually disappears when a value is entered.

Label
<div class="chi-form__item">
  <chi-label for="example__placeholder">Label</chi-label>
  <chi-text-input id="example__placeholder" placeholder="Placeholder"></chi-text-input>
</div>
<div class="chi-form__item">
  <label class="chi-label" for="example__placeholder">Label</label>
  <input type="text" class="chi-input" id="example__placeholder" placeholder="Placeholder">
</div>

Spinner#

Use the spinner attribute to let users know when information is saving or loading.

Label
<div class="chi-form__item">
  <chi-label for="example__spinner">Label</chi-label>
  <chi-text-input id="example__spinner" spinner></chi-text-input>
</div>
<div class="chi-form__item">
  <label class="chi-label" for="example__spinner">Label</label>
  <div class="chi-input__wrapper">
    <input type="text" class="chi-input" id="example__spinner">
    <svg class="chi-spinner -icon--muted" viewBox="0 0 66 66">
      <title>Loading</title>
      <circle class="path" cx="33" cy="33" r="30" fill="none" stroke-width="6"></circle>
    </svg>
  </div>
</div>

Required#

Use the required boolean attribute to indicate which inputs must be completed before submitting a form. This is useful for capturing important information and reducing the risk of form errors. To render a required input, apply the required attribute to the input. It is also encouraged but not mandatory to apply a required attribute to the corresponding label of the input which will automatically render a red asterisk. Note: For HTML Blueprint implementations, the required attribute is not supported on the label. Please use the alternate method specified below for rendering a red asterisk within the label.

Label
<div class="chi-form__item">
  <chi-label for="example__required" required>Label</chi-label>
  <chi-text-input id="example__required" required></chi-text-input>
</div>
<div class="chi-form__item">
  <label class="chi-label" for="example__required">
    Label
    <abbr class="chi-label__required" aria-label="Required field">*</abbr>
  </label>
  <input type="text" class="chi-input" id="example__required" required>
</div>

Optional#

When the vast majority of inputs in a form are required, optional can be used to help emphasize the few that are not. This is useful for inputs that are not relevant to all users, such as an Address Line 2 text input in a Billing or Shipping address form. If the user does not have an apartment, suite, or unit number, applying optional to chi-label will help convey the labels corresponding input is not required and can be skipped. Note: For HTML Blueprint implementations, the optional boolean attribute is not supported on the label. Please use the alternate method specified below for rendering optional text within the label.

Label
<div class="chi-form__item">
  <chi-label for="example__optional" optional>Label</chi-label>
  <chi-text-input id="example__optional"></chi-text-input>
</div>
<div class="chi-form__item">
  <label class="chi-label" for="example__optional">
    Label
    <abbr class="chi-label__optional" aria-label="Optional field">(optional)</abbr>
  </label>
  <input type="text" class="chi-input" id="example__optional">
</div>

Help#

Use chi-label's attributes infoIcon and infoIconMessage to include a help icon that displays helpful information in a popover.

Label
<div class="chi-form__item">
  <chi-label for="example__help" info-icon info-icon-message="Helpful information goes here.">Label</chi-label>
  <chi-text-input id="example__help"></chi-text-input>
</div>
This HTML Blueprint requires JavaScript. You may use your own solution, or use Chi's vanilla JavaScript solution, Chi.js.
<div class="chi-form__item">
  <div class="chi-label__wrapper">
    <label class="chi-label" for="example__help">Label</label>
    <div class="chi-label__help">
      <div class="chi-button -icon -flat -xs" id="example__help-button" data-target="#example__help-popover" aria-label="Help">
        <div class="chi-button__content">
          <i class="chi-icon icon-circle-info-outline" aria-hidden="true"></i>
        </div>
      </div>
      <section class="chi-popover chi-popover--top" id="example__help-popover" aria-modal="true" role="dialog">
        <div class="chi-popover__content">
          <p class="chi-popover__text">Helpful information goes here.</p>
        </div>
      </section>
    </div>
  </div>
  <input class="chi-input" id="example__help" type="text">
</div>

<script>chi.popover(document.getElementById('example__help-button'));</script>

Message#

Use the helper-message attribute to provide users with additional information, validation feedback, and other helpful information.

Label
<div class="chi-form__item">
  <chi-label for="example__message">Label</chi-label>
  <chi-text-input id="example__message" helper-message="Optional helper message"></chi-text-input>
</div>
<div class="chi-form__item">
  <label class="chi-label" for="example__message">Label</label>
  <input class="chi-input" id="example__message" type="text">
  <div class="chi-label -status">Optional helper message</div>
</div>

Copy text button#

Use the copy-text attribute to show a copy icon that provides the user the ability to copy the input value into the clipboard.

Label
<div class="chi-form__item">
  <chi-label for="example__copy-text-button">Label</chi-label>
  <chi-text-input value="Sample Text" id="example__copy-text-button" copy-text></chi-text-input>
</div>
<div class="chi-form__item">
  <label class="chi-label" for="example__copy-text-button">Label</label>
  <div class="-d--flex -align-items--center">
    <div class="chi-input__wrapper -flex--grow1">
      <input type="text" class="chi-input" value="Sample text" id="example__copy-text-button" />
    </div>

    <button id="example_copy-text-button" class="chi-button -icon -flat" aria-label="Button action" data-tooltip="Copy to clipboard">
      <div class="chi-button__content">
        <i class="chi-icon icon-copy -sm" aria-hidden="true"></i>
      </div>
    </button>
  </div>
</div>

<script>
  document.getElementById('example_copy-text-button').addEventListener('click', () => {
    navigator.clipboard?.writeText(
      document.getElementById('example__copy-text-button').getAttribute('value')
    );
  });

  <!-- Tooltip -->
  chi.tooltip(document.querySelectorAll('[data-tooltip]'));
</script>

Error#

Use the danger state to provide feedback to users when input data fails to validate. To meet accessibility requirements, danger inputs must include an error message explaining the failure and/or how to correct it.

Name
<div class="chi-form__item">
  <chi-label for="example__danger">Name</chi-label>
  <chi-text-input id="example__danger" state="danger" helper-message="Please enter a name"></chi-text-input>
</div>
<div class="chi-form__item">
  <label class="chi-label" for="example__portal-danger">Name</label>
  <input type="text" class="chi-input -danger" id="example__portal-danger">
  <div class="chi-label -status -danger">
    <i class="chi-icon icon-circle-warning" aria-hidden="true"></i>
    Please enter a name
  </div>
</div>

Layout Variations#

Inline Label#

Apply the class -row to chi-form__item to render labels and inputs inline.

Label
<div class="chi-form__item -row">
  <chi-label for="example__inline-label">Label</chi-label>
  <chi-text-input id="example__inline-label"></chi-text-input>
</div>
<div class="chi-form__item -row">
  <label class="chi-label" for="example__inline-label">Label</label>
  <input class="chi-input" type="text" id="example__inline-label">
</div>

Inline Label - width controlled using percent#

Label width 50%
<div class="chi-form__item -row">
  <chi-label class="-w--50" for="example__inline-label-percent">Label width 50%</chi-label>
  <div class="-w--50">
    <chi-text-input id="example__inline-label-percent"></chi-text-input>
  </div>
</div>
<div class="chi-form__item -row">
  <label class="chi-label -w--50" for="example__inline-label-percent">Label</label>
  <div class="-w--50">
    <input class="chi-input" type="text" id="example__inline-label-percent">
  </div>
</div>

Inline Label - width controlled using grid#

Label width 3 columns
<div class="chi-form__item -row chi-grid -no-gutter">
  <chi-label class="chi-col -w--3" for="example__inline-label-grid">Label width 3 columns</chi-label>
  <chi-text-input class="chi-col -w--9" id="example__inline-label-grid"></chi-text-input>
</div>
<div class="chi-form__item -row chi-grid -no-gutter">
  <label class="chi-label chi-col -w--3" for="example__inline-label-grid">Label</label>
  <input class="chi-input chi-col -w--9" type="text" id="example__inline-label-grid">
</div>

Inline Inputs#

Label
Label
<div class="-d--flex">
  <div class="chi-form__item -inline -flex--grow1">
    <chi-label for="example__inline-input01">Label</chi-label>
    <chi-text-input id="example__inline-input01"></chi-text-input>
  </div>
  <div class="chi-form__item -inline -flex--grow1">
    <chi-label for="example__inline-input02">Label</chi-label>
    <chi-text-input id="example__inline-input02"></chi-text-input>
  </div>
</div>
<div class="-d--flex">
  <div class="chi-form__item -inline -flex--grow1">
    <label class="chi-label" for="example__inline-input01">Label</label>
    <input class="chi-input" type="text" id="example__inline-input01">
  </div>
  <div class="chi-form__item -inline -flex--grow1">
    <label class="chi-label" for="example__inline-input02">Label</label>
    <input class="chi-input" type="text" id="example__inline-input02">
  </div>
</div>

Floating Label#

Use floating labels to keep the placeholder visible when no label is attached to the input. Note: Chi only supports floating labels on -md, -lg and -xl inputs.

This HTML Blueprint requires JavaScript. You may use your own solution, or use Chi's vanilla JavaScript solution, Chi.js.
<div class="chi-input__wrapper -floating-label">
  <input class="chi-input -md" type="text" id="floating-label-md">
  <label for="floating-label-md">Placeholder text</label>
</div>

<div class="chi-input__wrapper -floating-label">
  <input class="chi-input -lg" type="text" id="floating-label-lg">
  <label for="floating-label-lg">Placeholder text</label>
</div>

<div class="chi-input__wrapper -floating-label">
  <input class="chi-input -xl" type="text" id="floating-label-xl">
  <label for="floating-label-xl">Placeholder text</label>
</div>

<script>
  chi.floatingLabel(document.querySelectorAll('.-floating-label'));
</script>

Icons#

Left Aligned#

Label
<div class="chi-form__item">
  <chi-label for="example__icon-left-aligned">Label</chi-label>
  <chi-text-input icon-left="search" value="Sample Text" id="example__icon-left-aligned"></chi-text-input>
</div>
<div class="chi-form__item">
  <label class="chi-label" for="example__icon-left-aligned">Label</label>
  <div class="chi-input__wrapper -icon--left">
    <input type="text" class="chi-input" value="Sample text" id="example__icon-left-aligned">
    <i class="chi-icon icon-search" aria-hidden="true"></i>
    </div>
  </div>
</div>

Right Aligned#

Label
<div class="chi-form__item">
  <chi-label for="example__icon-right-aligned">Label</chi-label>
  <chi-text-input icon-right="search" value="Sample Text" id="example__icon-right-aligned"></chi-text-input>
</div>
<div class="chi-form__item">
  <label class="chi-label" for="example__icon-right-aligned">Label</label>
  <div class="chi-input__wrapper -icon--right">
    <input type="text" class="chi-input" value="Sample text" id="example__icon-right-aligned">
    <i class="chi-icon icon-search" aria-hidden="true"></i>
  </div>
</div>

Left + Right Aligned#

Label
<div class="chi-form__item">
  <chi-label for="example__icon-left-right-aligned">Label</chi-label>
  <chi-text-input icon-left="search" icon-right="check" icon-right-color="success" value="Sample Text" id="example__icon-left-right-aligned"></chi-text-input>
</div>
<div class="chi-form__item">
  <label class="chi-label" for="example__icon-left-right-aligned">Label</label>
  <div class="chi-input__wrapper -icon--left -icon--right">
    <input type="text" class="chi-input" value="Sample text" id="example__icon-left-right-aligned">
    <i class="chi-icon icon-search" aria-hidden="true"></i>
    <i class="chi-icon icon-check -icon--success" aria-hidden="true"></i>
  </div>
</div>

Icons#

Left Aligned#

Label
<div class="chi-form__item">
  <chi-label for="example__portal-icon-left-aligned">Label</chi-label>
  <chi-text-input icon-left="search" value="Sample Text" id="example__portal-icon-left-aligned"></chi-text-input>
</div>
<div class="chi-form__item">
  <label class="chi-label" for="example__portal-icon-left-aligned">Label</label>
  <div class="chi-input__wrapper -icon--left">
    <input type="text" class="chi-input" value="Sample text" id="example__portal-icon-left-aligned">
    <i class="chi-icon icon-search" aria-hidden="true"></i>
    </div>
  </div>
</div>

Right Aligned#

Label
<div class="chi-form__item">
  <chi-label for="example__portal-icon-right-aligned">Label</chi-label>
  <chi-text-input icon-right="search" value="Sample Text" id="example__portal-icon-right-aligned"></chi-text-input>
</div>
<div class="chi-form__item">
  <label class="chi-label" for="example__portal-icon-right-aligned">Label</label>
  <div class="chi-input__wrapper -icon--right">
    <input type="text" class="chi-input" value="Sample text" id="example__portal-icon-right-aligned">
    <i class="chi-icon icon-search" aria-hidden="true"></i>
  </div>
</div>

Left + Right Aligned#

Label
<div class="chi-form__item">
  <chi-label for="example__portal-icon-left-right-aligned">Label</chi-label>
  <chi-text-input icon-left="search" icon-right="check" value="Sample Text" id="example__portal-icon-left-right-aligned"></chi-text-input>
</div>
<div class="chi-form__item">
  <label class="chi-label" for="example__portal-icon-left-right-aligned">Label</label>
  <div class="chi-input__wrapper -icon--left -icon--right">
    <input type="text" class="chi-input" value="Sample text" id="example__portal-icon-left-right-aligned">
    <i class="chi-icon icon-search" aria-hidden="true"></i>
    <i class="chi-icon icon-check" aria-hidden="true"></i>
  </div>
</div>

Sizes#

Text inputs supports the following sizes: xs, sm, md, lg, and xl. The default size is md.

Label
Label
Label
Label
Label
<div class="chi-form__item">
  <chi-label for="example__size-xs">Label</chi-label>
  <chi-text-input size="xs" id="example__size-xs"></chi-text-input>
</div>
<div class="chi-form__item">
  <chi-label for="example__size-sm">Label</chi-label>
  <chi-text-input size="sm" id="example__size-sm"></chi-text-input>
</div>
<div class="chi-form__item">
  <chi-label for="example__size-md">Label</chi-label>
  <chi-text-input size="md" id="example__size-md"></chi-text-input>
</div>
<div class="chi-form__item">
  <chi-label for="example__size-lg">Label</chi-label>
  <chi-text-input size="lg" id="example__size-lg"></chi-text-input>
</div>
<div class="chi-form__item">
  <chi-label for="example__size-xl">Label</chi-label>
  <chi-text-input size="xl" id="example__size-xl"></chi-text-input>
</div>
<div class="chi-form__item">
  <label class="chi-label" for="example__size-sm">Label</label>
  <input type="text" class="chi-input -xs" id="example__size-sm">
</div>
<div class="chi-form__item">
  <label class="chi-label" for="example__size-sm">Label</label>
  <input type="text" class="chi-input -sm" id="example__size-sm">
</div>
<div class="chi-form__item">
  <label class="chi-label" for="example__size-md">Label</label>
  <input type="text" class="chi-input -md" id="example__size-md">
</div>
<div class="chi-form__item">
  <label class="chi-label" for="example__size-lg">Label</label>
  <input type="text" class="chi-input -lg" id="example__size-lg">
</div>
<div class="chi-form__item">
  <label class="chi-label" for="example__size-xl">Label</label>
  <input type="text" class="chi-input -xl" id="example__size-xl">
</div>

Sizes#

Text inputs supports the following sizes: xs, sm, md, lg. The default size is md.

Label
Label
Label
Label
<div class="chi-form__item">
  <chi-label for="example__size-xs">Label</chi-label>
  <chi-text-input size="xs" id="example__size-xs"></chi-text-input>
</div>
<div class="chi-form__item">
  <chi-label for="example__size-sm">Label</chi-label>
  <chi-text-input size="sm" id="example__size-sm"></chi-text-input>
</div>
<div class="chi-form__item">
  <chi-label for="example__size-md">Label</chi-label>
  <chi-text-input size="md" id="example__size-md"></chi-text-input>
</div>
<div class="chi-form__item">
  <chi-label for="example__size-lg">Label</chi-label>
  <chi-text-input size="lg" id="example__size-lg"></chi-text-input>
</div>
<div class="chi-form__item">
  <label class="chi-label" for="example__size-sm">Label</label>
  <input type="text" class="chi-input -xs" id="example__size-sm">
</div>
<div class="chi-form__item">
  <label class="chi-label" for="example__size-sm">Label</label>
  <input type="text" class="chi-input -sm" id="example__size-sm">
</div>
<div class="chi-form__item">
  <label class="chi-label" for="example__size-md">Label</label>
  <input type="text" class="chi-input -md" id="example__size-md">
</div>
<div class="chi-form__item">
  <label class="chi-label" for="example__size-lg">Label</label>
  <input type="text" class="chi-input -lg" id="example__size-lg">
</div>

Web Component#

Properties#

Property
Attribute
Description
Type
Default
copyText
copy-text
To show copy text icon
boolean
false
disabled
disabled
To disable Text input
boolean
false
helperMessage
helper-message
To display an additional helper text message below the Text input
string
undefined
iconLeft
icon-left
To add a left positioned icon
string
undefined
iconLeftColor
icon-left-color
To define color of left icon
"danger" | "dark" | "grey" | "info" | "light" | "muted" | "navy" | "orange" | "primary" | "secondary" | "success" | "warning"
undefined
iconRight
icon-right
To add a right positioned icon
string
undefined
iconRightColor
icon-right-color
To define color of right icon
"danger" | "dark" | "grey" | "info" | "light" | "muted" | "navy" | "orange" | "primary" | "secondary" | "success" | "warning"
undefined
name
name
To define name of Text input
string
undefined
placeholder
placeholder
To define placeholder of Text input
string
undefined
preventValueMutation
prevent-value-mutation
To disable Value attribute mutation
boolean
false
readonly
readonly
To prevent the Text input value from being changed
boolean
false
size
size
To define size of Text input
"lg" | "md" | "sm" | "xl" | "xs"
'md'
spinner
spinner
To render Text Input with Spinner
boolean
false
state
state
To define state color of Text input
"danger" | "success" | "warning"
undefined
type
type
To define type of Text input
"date" | "datetime" | "datetime-local" | "email" | "month" | "number" | "password" | "search" | "tel" | "text" | "time" | "url" | "week"
'text'
value
value
To define value of Text input
string
''

Events#

Event
Description
Type
chiBlur
Triggered when the element has lost focus.
CustomEvent<any>
chiChange
Triggered when an alteration to the element's value is committed by the user
CustomEvent<string>
chiFocus
Triggered when the user sets focus on the element.
CustomEvent<any>
chiInput
Triggered when the user changed the element's value but did not commit the change yet
CustomEvent<string>

Accessibility#

Keyboard Navigation#

KeyFunction
TabMoves focus to the next focusable element
Shift + TabMoves focus to the previous focusable element
SpaceActivates the button

For comprehensive details on keyboard support for input fields, refer to our Keyboard Control Guide.

Visit WebAIM for keyboard techniques.

Guidance for developers
  • Simplify forms for better browser compatibility.
  • Use labels for inputs, matching for and id attributes.
  • Keep IDs unique and pair each form element with one label.
  • Mark required fields clearly (e.g., with an asterisk).
  • Use aria-describedby for error message accessibility.
  • if there's an error message tagged with id="my-error-message", then the corresponding input must include aria-describedby="my-error-message"
Guidance for designers
  • Ensure focus indicators are visible to aid navigation.
  • Keep input labels visible, even when fields are focused.
  • Use contrasting colors for text and backgrounds to enhance readability.
  • Design clear error states and feedback for accessibility.
  • Use spacing, typography, and visual cues effectively.
  • Maintain consistency in the design of input elements to provide a cohesive user experience.

For hands-on examples, consult the Accessibility (A11y) Style Guide.

Resources#

Other recommendations#

Explore additional accessibility tips in the general Accessibility Guide.

WCAG 2.2 Guidelines#

  • Non-text Content: All non-text content that is presented to the user has a text alternative that serves the equivalent purpose. (Level A)
  • Info and Relationships: Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text. (Level A)
  • Headings and Labels: Headings and labels describe topic or purpose. (Level AA)
  • Labels or Instructions: Labels or instructions are provided when content requires user input. (Level A)
  • Name, Role, Value: For all user interface components (including but not limited to: form elements, links and components generated by scripts), the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to user agents, including assistive technologies. (Level A)