# auro-input
The `auro-input` element provides users a way to enter data into a text field.
## Properties
| Property | Attribute | Type | Default | Description |
|-----------------------------------|-----------------------------------|--------------------------------------------------|-------------|--------------------------------------------------|
| `a11yActivedescendant` | `a11yActivedescendant` | `string` | | The value for the aria-activedescendant attribute.
Points to the ID of the currently active/highlighted option in a listbox. |
| `a11yControls` | `a11yControls` | `string` | | The value for the aria-controls attribute. |
| `a11yExpanded` | `a11yExpanded` | `boolean` | | The value for the aria-expanded attribute. |
| `a11yRole` | `a11yRole` | `string` | | The value for the role attribute. |
| [activeLabel](#activeLabel) | `activeLabel` | `boolean` | | If set, the label will remain fixed in the active position. |
| [appearance](#appearance) | `appearance` | `'default' \| 'inverse'` | "'default'" | Defines whether the component will be on lighter or darker backgrounds. |
| [autocapitalize](#autocapitalize) | `autocapitalize` | `string` | | An enumerated attribute that controls whether and how text input is automatically capitalized as it is entered/edited by the user. [off/none, on/sentences, words, characters]. |
| [autocomplete](#autocomplete) | `autocomplete` | `string` | | An enumerated attribute that defines what the user agent can suggest for autofill. At this time, only `autocomplete="off"` is supported. |
| [autocorrect](#autocorrect) | `autocorrect` | `string` | | When set to `off`, stops iOS from auto-correcting words when typed into a text box. |
| [customValidityTypeEmail](#customValidityTypeEmail) | `customValidityTypeEmail` | `string` | | Custom help text message for email type validity. |
| [disabled](#disabled) | `disabled` | `boolean` | | If set, disables the input. |
| [dvInputOnly](#dvInputOnly) | `dvInputOnly` | `boolean` | | If defined, the display value slot content will only mask the HTML5 input element. The input's label will not be masked. |
| [error](#error) | `error` | `string` | | When defined, sets persistent validity to `customError` and sets `setCustomValidity` = attribute value. |
| [errorMessage](#errorMessage) | `errorMessage` | `string` | | Contains the help text message for the current validity error. |
| [format](#format) | `format` | `string` | | Specifies the input mask format. |
| [hasFocus](#hasFocus) | | `boolean` | | Flag to indicate if the input currently has focus. |
| [hasValue](#hasValue) | | `boolean` | | Flag to indicate if the input currently has value. |
| [icon](#icon) | `icon` | `boolean` | | If set, will render an icon inside the input to the left of the value. Support is limited to auro-input instances with credit card format. |
| [id](#id) | `id` | `string` | | The id global attribute defines an identifier (ID) which must be unique in the whole document. |
| [inputmode](#inputmode) | `inputmode` | `string` | | Exposes inputmode attribute for input. |
| [lang](#lang) | `lang` | `string` | | Defines the language of an element. |
| [layout](#layout) | | `string` | | |
| [max](#max) | `max` | `string` | | The maximum value allowed. This only applies for inputs with a type of `number` and all date formats. |
| [maxLength](#maxLength) | `maxLength` | `number` | | The maximum number of characters the user can enter into the text input. This must be an integer value `0` or higher.
**Note**: This attribute is not intended to be used with a `type` or `format` that already has a defined length, such as credit-cards, dates or phone numbers. |
| [min](#min) | `min` | `string` | | The minimum value allowed. This only applies for inputs with a type of `number` and all date formats. |
| [minLength](#minLength) | `minLength` | `number` | | The minimum number of characters the user can enter into the text input. This must be a non-negative integer value smaller than or equal to the value specified by `maxlength`. |
| [name](#name) | `name` | `string` | | Populates the `name` attribute on the input. |
| [nested](#nested) | `nested` | `boolean` | | Sets styles for nested operation - removes borders, hides help + error text, and
hides accents. |
| [noValidate](#noValidate) | `noValidate` | `boolean` | | If set, disables auto-validation on blur. |
| [onDark](#onDark) | `onDark` | `boolean` | | DEPRECATED - use `appearance="inverse"` instead. |
| [pattern](#pattern) | `pattern` | `string` | | Specifies a regular expression the form control's value should match. |
| [placeholder](#placeholder) | `placeholder` | `string` | | Define custom placeholder text. |
| [readonly](#readonly) | `readonly` | `boolean` | | Makes the input read-only, but can be set programmatically. |
| [required](#required) | `required` | `boolean` | | Populates the `required` attribute on the input. Used for client-side validation. |
| [setCustomValidity](#setCustomValidity) | `setCustomValidity` | `string` | | Sets a custom help text message to display for all validityStates. |
| [setCustomValidityBadInput](#setCustomValidityBadInput) | `setCustomValidityBadInput` | `string` | | Custom help text message to display when validity = `badInput`. |
| [setCustomValidityCustomError](#setCustomValidityCustomError) | `setCustomValidityCustomError` | `string` | | Custom help text message to display when validity = `customError`. |
| [setCustomValidityForType](#setCustomValidityForType) | `setCustomValidityForType` | `string` | | Custom help text message to display for the declared element `type` and type validity fails. |
| [setCustomValidityRangeOverflow](#setCustomValidityRangeOverflow) | `setCustomValidityRangeOverflow` | `string` | | Custom help text message to display when validity = `rangeOverflow`. |
| [setCustomValidityRangeUnderflow](#setCustomValidityRangeUnderflow) | `setCustomValidityRangeUnderflow` | `string` | | Custom help text message to display when validity = `rangeUnderflow`. |
| [setCustomValidityTooLong](#setCustomValidityTooLong) | `setCustomValidityTooLong` | `string` | | Custom help text message to display when validity = `tooLong`. |
| [setCustomValidityTooShort](#setCustomValidityTooShort) | `setCustomValidityTooShort` | `string` | | Custom help text message to display when validity = `tooShort`. |
| [setCustomValidityValueMissing](#setCustomValidityValueMissing) | `setCustomValidityValueMissing` | `string` | | Custom help text message to display when validity = `valueMissing`. |
| [simple](#simple) | `simple` | `boolean` | | Simple makes the input render without a border. |
| [spellcheck](#spellcheck) | `spellcheck` | `string` | | An enumerated attribute defines whether the element may be checked for spelling errors. [true, false]. When set to `false` the attribute `autocorrect` is set to `off` and `autocapitalize` is set to `none`. |
| [type](#type) | `type` | `'text' \| 'password' \| 'email' \| 'credit-card' \| 'tel' \| 'number'` | "'text'" | Populates the `type` attribute on the input. |
| [validateOnInput](#validateOnInput) | `validateOnInput` | `boolean` | | Sets validation mode to re-eval with each input. |
| [validity](#validity) | `validity` | `string` | | Specifies the `validityState` this element is in. |
| [value](#value) | `value` | `string` | | Populates the `value` attribute on the input. Can also be read to retrieve the current value of the input. |
## Methods
| Method | Type | Description |
|------------|----------------------------------------|--------------------------------------------------|
| [clear](#clear) | `(): void` | Clears the input value. |
| [focus](#focus) | `(): void` | Function to set element focus. |
| [reset](#reset) | `(): void` | Resets component to initial state, including resetting the touched state and validity. |
| [validate](#validate) | `(force?: boolean \| undefined): void` | Validates value.
**force**: Whether to force validation. |
## Events
| Event | Type | Description |
|-----------------------------|--------------------|--------------------------------------------------|
| `auroFormElement-validated` | | Notifies that the `validity` and `errorMessage` value has changed. |
| `auroInput-validityChange` | `CustomEvent` | |
| [input](#input) | `InputEvent` | Event fires when the value of an `auro-input` has been changed. |
## Slots
| Name | Description |
|---------------------------|--------------------------------------------------|
| `ariaLabel.clear` | Sets aria-label on clear button for screen reader to read |
| `ariaLabel.password.hide` | Sets aria-label on password button to toggle off showing password |
| `ariaLabel.password.show` | Sets aria-label on password button to toggle on showing password |
| [displayValue](#displayValue) | Allows custom HTML content to display in place of the value when the input is not focused. |
| [helpText](#helpText) | Sets the help text displayed below the input. |
| [label](#label) | Sets the label text for the input. |
| [optionalLabel](#optionalLabel) | Allows overriding the optional display text "(optional)", which appears next to the label. |
## CSS Shadow Parts
| Part | Description |
|-----------------|--------------------------------------------------|
| `accent-left` | Use for customizing the style of the left accent element (e.g. padding, margin) |
| `accent-right` | Use for customizing the style of the right accent element (e.g. padding, margin) |
| [accentIcon](#accentIcon) | Use for customizing the style of the accentIcon element (e.g. credit card icon, calendar icon) |
| [displayValue](#displayValue) | Use for customizing the style of the displayValue element |
| [helpText](#helpText) | Use for customizing the style of the helpText element |
| [iconContainer](#iconContainer) | Use for customizing the style of the iconContainer (e.g. X icon for clearing input value) |
| [input](#input) | Use for customizing the style of the input element |
| [inputHelpText](#inputHelpText) | Use for customizing the style of the input help text wrapper |
| [label](#label) | Use for customizing the style of the label element |
| [wrapper](#wrapper) | Use for customizing the style of the root element |
## Basic
Clear All
Label
Help Text
See code
```html
Clear All
Label
Help Text
```
## Property & Attribute Examples
### Active Label
Use the `activeLabel` attribute to make the label stay fixed in the active position.
Address
Please enter your home address.
See code
```html
Address
Please enter your home address.
```
### Appearance on Dark Backgrounds
See code
```html
Label
Help Text
```
### Disabled
Use the `disable` attribute to prevent the user from interacting with the input.
See code
```html
Disabled
Help Text
```
See code
```html
Arrival date
Help Text
```
### Error
Use the `error` attribute to apply a persistent custom error that supersedes the HTML5 validation logic.
A custom error message can be set using the `error` attribute, or it can be used in conjuction with the `setCustomValidityCustomError` attribute.
Set Custom Error
Clear Custom Error
Name
Please enter your full name.
See code
```html
Set Custom Error
Clear Custom Error
Name
Please enter your full name.
```
```js
export function customError() {
const elem = document.querySelector('#setCustomErrorExample');
// set custom error
document.querySelector('#setCustomErrorBtn').addEventListener('click', () => {
elem.error = "Custom Error Message";
});
// remove custom error
document.querySelector('#setCustomErrorClearBtn').addEventListener('click', () => {
elem.removeAttribute('error');
});
}
```
Set Custom Error
Clear Custom Error
Name
Please enter your full name.
See code
```html
Set Custom Error
Clear Custom Error
Name
Please enter your full name.
```
```js
export function customErrorOnDark() {
const elem = document.querySelector('#setCustomErrorExampleOnDark');
// set custom error
document.querySelector('#setCustomErrorBtnOnDark').addEventListener('click', () => {
elem.error = "Custom Error Message";
});
// remove custom error
document.querySelector('#setCustomErrorClearBtnOnDark').addEventListener('click', () => {
elem.removeAttribute('error');
});
}
```
### Format
Use the `format` attribute to set the format of the IMask.
Default masking definitions:
- 0 : number
- a : letter
- \* : any character
See [IMask](https://imask.js.org/) for more information on how to configure a mask.
Custom format
Format is: 47440000
See code
```html
Custom format
Format is: 47440000
```
#### Input Mode
Set the `inputmode` for the input.
**IMPORTANT**: If you are also passing a `type`, most browsers will use the `type` attribute to determine what keyboard to display on mobile devices and ignore the `inputmode` attribute.
See code
```html
Telephone
Help Text
```
### Max
Use the `max` attribute to define a maximum value used during validation. The attribute will only apply when `` also has a `type` attribute for `number` or any date format.
The `setCustomValidityRangeOverflow` attribute may optionally be used in combination with the `max` attribute to define custom help text used when the input value is greater than the value of the `max` attribute.
#### Date Example
See code
```html
Choose a date
Help Text
```
#### Number Example
Choose a number
Help Text
See code
```html
Choose a number
Help Text
```
### Max Length
Use the `maxlength` attribute to control the length of the input entered.
The `setCustomValidityTooLong` attribute may optionally be used in combination with the `maxLength` attribute to define custom help text used when the length of the input is too long.
**Note**: This attribute is not intended to be used with a `type` or `format` that already has a defined length, such as credit-cards, dates or phone numbers.
Voucher Code
Please enter your 12 character voucher code.
See code
```html
Voucher Code
Please enter your 12 character voucher code.
```
### Min
Use the `min` attribute to define a minimum value used during validation. The attribute will only apply when `` also has a `type` attribute for `number` or any date format.
The `setCustomValidityRangeUnderflow` attribute may optionally be used in combination with the `min` attribute to define custom help text used when the input value is less than the value of the `min` attribute.
#### Date Example
See code
```html
Choose a date
Help Text
```
#### Number Example
Choose a number
Help Text
See code
```html
Choose a number
Help Text
```
### Min Length
Use the `minlength` attribute to control the length of the input entered.
The `setCustomValidityTooShort` attribute may optionally be used in combination with the `minLength` attribute to define custom help text used when the length of the input is not long enough.
Voucher Code
Please enter your 4 character voucher code.
See code
```html
Voucher Code
Please enter your 4 character voucher code.
```
### No Validate
For use cases where the field is `required`, but live validation is not wanted, use the `noValidate` attribute.
Address
Please enter your home address.
See code
```html
Address
Please enter your home address.
```
### Pattern
Use the `pattern` attribute to set custom input validation. This example also uses the `spellcheck` attribute set to `false` which in turn sets `autocorrect` to `off` and `autocapitalize` to `none`. Additionally the `maxlength` attribute sets the maximum length of characters that can be entered.
The `` component supports setting a custom validity message specific to the pattern validation by using the `setCustomValidityPatternMismatch` attribute.
Username
Please enter a username.
See code
```html
Username
Please enter a username.
```
### Placeholder
Use the `placeholder` attribute to add a custom placeholder message within the element.
Full name
Please enter your full name.
See code
```html
Full name
Please enter your full name.
```
### Readonly
Use the `readonly` attribute to prevent the user from editing the value of the input.
In this example, the user is able to programmatically change the value of the input by clicking the button or clear out the contents of the input.
Set Value to Auro Alaska
Reset
Name
Please enter your full name.
See code
```html
Set Value to Auro Alaska
Reset
Name
Please enter your full name.
```
```js
export function setReadonlyValue() {
const elem = document.querySelector('#readonlyExample');
// set value of auro-input element
document.querySelector('#setReadonlyValueBtn').addEventListener('click', () => {
elem.value = "Auro Alaska";
});
document.querySelector('#resetReadonlyValueBtn').addEventListener('click', () => {
elem.value = undefined;
});
}
```
### Required
When present, the `required` attribute specifies that an input field must be filled out before submitting the form.
When the validity check fails, the validityState equals `valueMissing`. The error message for the `valueMissing` validityState can be changed to a custom string using the `setCustomValidityValueMissing`.
Full name
Please enter your full name.
See code
```html
Full name
Please enter your full name.
```
### Set Custom Validity
The `setCustomValidity` attribute can be used to set a custom string for all validityStates. When the component is first loaded, if this attribute is set on the element, all validityStates (except `valid`) will display the defined message.
**NOTE:** Custom strings are NOT localized. It is the responsibility of the element consumer to provide localized strings when using this element property.
Full Name
Please enter your full name.
See code
```html
Full Name
Please enter your full name.
```
### Type
#### Password
Use the `type="password"` attribute for a password style input. The hide/show password feature will automatically appear once a user begins to enter data.
Default help text will be added to the input `type="password"` if custom help text is not provided. See the example below.
Clear All
Show
Hide
Password
Please enter a secure password.
See code
```html
Clear All
Show
Hide
Password
Please enter a secure password.
```
Password
Please enter a secure password.
See code
```html
Password
Please enter a secure password.
```
#### Email
Use the `type="email"` attribute for a email style input. These examples illustrate the default error messaging per that browser. Content may vary.
Default help text will be added to the input `type="email"` if custom help text is not provided. See the example below.
Email address
Please enter your email address.
See code
```html
Email address
Please enter your email address.
```
#### Number
Use the `type="number"` attribute for a numeric style input and invoke a numeric virtual keyboard on handheld devices.
This `number` input type should only be used for incremental numeric values, meaning values with decimals will be considered invalid. The `number` input type is not appropriate for values that happen to only consist of but aren't strictly speaking a number, such as postal codes in many countries or credit card numbers. See [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/number) for more information.
Number of Passengers
Please enter the number of passengers.
See code
```html
Number of Passengers
Please enter the number of passengers.
```
#### Credit Card
Use the `type="credit-card"` attribute for a credit card formatted input.
Default help text will be added to the input `type="credit-card"` if custom help text is not provided. See the example below.
Card number
Valid credit card numbers must include 16 digits (15 for Amex).
See code
```html
Card number
Valid credit card numbers must include 16 digits (15 for Amex).
```
Use the `type="credit-card"` and `icon` attributes for a credit card formatted input with credit card icon support.
**Dependency**: Please be sure to also install [auro-icon](https://auro.alaskaair.com/components/auro/icon/install) as a peer dependency.
Card number
Valid credit card numbers must include 16 digits (15 for Amex).
See code
// Use 4147 3411 1111 1111 to see the Alaska Airline's credit card!
```html
Card number
Valid credit card numbers must include 16 digits (15 for Amex).
```
#### Phone Number
Use the `type="tel"` attribute for a phone number formatted input. The default format is `+1 (000) 000-0000`.
See code
```html
Telephone
Help Text
```
#### Phone Number Formatting
Use the `format` attribute to set a custom phone number format.
See code
```html
Telephone
Help Text
```
#### Date
Use the `type="date"` attribute for a date formatted input. The default date format is `mm/dd/yyyy`.
See code
```html
Arrival date
Help Text
```
#### Date Formatting
Use the `format` attribute to put together any combination of `mm`, `dd`, & `yyyy` or `yy`.
See code
```html
Arrival date
Help Text
```
Expiration date
Help Text
See code
```html
Expiration date
Help Text
```
See code
```html
Day
Help Text
```
### Validate on Input
Use the `validateOnInput` attribute to enable live validation on the `input` event. Recommended use is with setting a custom `pattern` and validation is required prior to a `blur` event.
Full Name
Please enter your full name as it appears on the card.
See code
```html
Full Name
Please enter your full name as it appears on the card.
```
### Value
Use the `value` attribute to programmatically set the value of the input.
Name
Please enter your full name.
See code
```html
Name
Please enter your full name.
```
#### Dynamically Set Value
Use the `value` and other components to dynamically set the value of the input.
Note: Setting the `value` to `undefined` will also reset the element.
Set Value to Alaska
Set Value to Undefined
Name
Please enter your full name.
See code
```html
Set Value to Alaska
Set Value to Undefined
Name
Please enter your full name.
```
```js
export function programmaticallySetValue() {
const elem = document.querySelector('#setProgrammaticValueExample');
// set value of auro-input element
document.querySelector('#setValidValueBtn').addEventListener('click', () => {
elem.value = "Alaska Airlines is the best";
});
// reset the value of auro-input element
document.querySelector('#setUndefinedValueBtn').addEventListener('click', () => {
elem.value = undefined;
});
}
```
## Method Examples
### Reset State
Use the `reset()` method to reset the ``'s `value` and `validity` state. Doing so will preserve all other attributes and properties.
Reset
Full Name
Please enter your full name.
See code
```html
Reset
Full Name
Please enter your full name.
```
```js
export function resetStateExample() {
const elem = document.querySelector('#resetStateExample');
document.querySelector('#resetStateBtn').addEventListener('click', () => {
elem.reset();
});
}
```
## Slot Examples
### Custom Optional Label
The `` supports an `optionalLabel` slot, where users can can override the default `(optional)` notification text.
Full name
- optional
Please enter your full name.
See code
```html
Full name
- optional
Please enter your full name.
```
## Common Usage Patterns & Functional Examples
### Swapping Values Between Inputs
Example illustrates using a JavaScript function attached to an `auro-button` component `click` event to swap the values of two `auro-input` elements. An example of this use case would be swapping the departure and arrival airports in a flight search form.
Left Input
Help Text
Swap Values
Right Input
Help Text
See code
```html
Left Input
Help Text
Swap Values
Right Input
Help Text
```
```js
export function swapInputValues() {
const btn = document.querySelector('#swapExampleBtn');
const inputOne = document.querySelector('#swapExampleLeft');
const inputTwo = document.querySelector('#swapExampleRight');
btn.addEventListener('click', () => {
const valueOne = inputOne.value;
const valueTwo = inputTwo.value;
inputOne.value = valueTwo;
inputTwo.value = valueOne;
});
}
```
## Restyle Component with CSS Variables
The component may be restyled by changing the values of the following token(s).
```scss
/* stylelint-disable custom-property-empty-line-before */
@use "@aurodesignsystem/design-tokens/dist/themes/alaska/SCSSVariables--alaska" as v;
:host(:not([ondark])),
:host(:not([appearance="inverse"])) {
--ds-auro-input-border-color: var(--ds-basic-color-border-bold, #{v.$ds-basic-color-border-bold});
--ds-auro-input-container-color: var(--ds-basic-color-surface-default, #{v.$ds-basic-color-surface-default});
--ds-auro-input-caret-color: var(--ds-advanced-color-state-focused, #{v.$ds-advanced-color-state-focused});
--ds-auro-input-label-text-color: var(--ds-basic-color-texticon-muted, #{v.$ds-basic-color-texticon-muted});
--ds-auro-input-placeholder-text-color: var(--ds-basic-color-texticon-default, #{v.$ds-basic-color-texticon-default});
--ds-auro-input-text-color: var(--ds-basic-color-texticon-default, #{v.$ds-basic-color-texticon-default});
--ds-auro-input-error-icon-color: var(--ds-basic-color-status-error, #{v.$ds-basic-color-status-error});
--ds-auro-input-outline-color: transparent;
}
:host([ondark]),
:host([appearance="inverse"]) {
--ds-auro-input-border-color: var(--ds-basic-color-border-inverse, #{v.$ds-basic-color-border-inverse});
--ds-auro-input-container-color: var(--ds-advanced-color-shared-background-inverse, #{v.$ds-advanced-color-shared-background-inverse});
--ds-auro-input-caret-color: var(--ds-advanced-color-state-focused-inverse, #{v.$ds-advanced-color-state-focused-inverse});
--ds-auro-input-label-text-color: var(--ds-basic-color-texticon-inverse-muted, #{v.$ds-basic-color-texticon-inverse-muted});
--ds-auro-input-placeholder-text-color: var(--ds-basic-color-texticon-inverse, #{v.$ds-basic-color-texticon-inverse});
--ds-auro-input-text-color: var(--ds-basic-color-texticon-inverse, #{v.$ds-basic-color-texticon-inverse});
--ds-auro-input-error-icon-color: var(--ds-advanced-color-state-error-inverse, #{v.$ds-advanced-color-state-error-inverse});
--ds-auro-input-outline-color: transparent;
}
```