Text input
Examples
Base
<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.
<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.
<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.
<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.
<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.
<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.
<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__help
to include a help icon that displays helpful information about an input in a popover.
A help icon must be contained within an icon button to ensure it receives focus when a user tabs through a form.
<div class="chi-form__item">
<div class="chi-label__wrapper">
<chi-label for="example__label-with-icon">Label</chi-label>
<div class="chi-label__help">
<chi-button id="example__help-button" type="icon" size="xs" variant="flat" alternative-text="Help">
<chi-icon icon="circle-info-outline"></chi-icon>
</chi-button>
<chi-popover id="example__help-popover" position="top" variant="text" arrow reference="#example__help-button">
Helpful information goes here.
</chi-popover>
</div>
</div>
<chi-text-input id="example__label-with-icon"></chi-text-input>
</div>
<script>
document.querySelector("#example__help-button")
.addEventListener("click", function() {
var popoverElem = document.querySelector("#example__help-popover");
popoverElem.toggle();
});
</script>
<div class="chi-form__item">
<div class="chi-label__wrapper">
<label class="chi-label" for="example__label-with-icon">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__label-with-icon" 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.
<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.
<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.
<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.
<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
<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
<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
<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.
<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
<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
<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
<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
<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
<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
<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
.
<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
.
<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
Events
Accessibility
Keyboard Navigation
Key | Function |
---|---|
Tab | Moves focus to the next focusable element |
Shift + Tab | Moves focus to the previous focusable element |
Space | Activates the button |
For comprehensive details on keyboard support for input fields, refer to our Keyboard Control Guide.
Visit WebAIM for keyboard techniques.
For hands-on examples, consult the Accessibility (A11y) Style Guide.
Resources
- ARIA Practices: Detailed ARIA guidance for accessible web content, focusing on text inputs.
- A11y Style Guide: Outlines essential principles for accessible inputs and textareas.
- W3C Forms Tutorial: Provides guidance on creating accessible forms.
- DigitalA11y Project: Showcases live examples of accessible inputs of various types.
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)