Inputs are text containers which can be used to create forms, enter data, and enact various commands.
Overview
Input is an extremely robust set of components designed to fill many needs throughout an interface. With the ability to have prefixes, suffixes, clear controls, icons, and buttons, Inputs can visually accomplish almost any stylistic need. Inputs also have the ability to have error states, as well as used in coordination with Input Message for hints, validation, and other important contextual feedback.
Inputs contain multiple types, such as "text", "number", "email", "password", "file", "tel", "search", "time", "date", etc.
Usage
- Text or number entries
- Any type of entry tied to validation
- Data entry
- Form elements
Sample
Accessibility
Keyboard navigation
| Key | Function |
|---|---|
Tab | Moves focus in and out of the component. |
Tab and Shift | Moves focus in and out of the component. |
Esc | If the component is focused and clearable with a value - will clear the value. |
API reference
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
| accept | accept | When type is "file", specifies a comma separated list of unique file type specifiers for limiting accepted file types.
Read the native attribute's documentation on MDN for more info. | string | |
| alignment | alignment | Specifies the text alignment of the component's value. | Extract<"start" | "end", Alignment> | "start" |
| autocomplete | autocomplete | Specifies the type of content to autocomplete, for use in forms. Read the native attribute's documentation on MDN for more info. | AutoFill | |
| clearable | clearable | When true and the component has a value, a clear button is displayed. The clear button shows by default for "search", "time", and "date" types. | boolean | false |
| disabled | disabled | When true, prevents interaction and decreases the component's opacity. | boolean | false |
| files | When type is "file", specifies the component's selected files. | FileList | undefined | ||
| form | form | Specifies the id of the component's associated form.
When not set, the component is associated with its ancestor form element, if one exists. | string | |
| groupSeparator | group-separator | When true, number values are displayed with a group separator corresponding to the language and country format. | boolean | false |
| icon | icon | When true, displays a default recommended icon. Alternatively, pass a Calcite UI Icon name to display a specific icon. | IconName | boolean | |
| iconFlipRtl | icon-flip-rtl | When true and the element direction is right-to-left ("rtl"), flips the components icon`. | boolean | false |
| label | label | Specifies an accessible label for the component. | string | |
| labelText | label-text | Specifies the component's label text. | string | |
| loading | loading | When true, a busy indicator is displayed. | boolean | false |
| max | max | When the component resides in a form,
specifies the maximum value for type="number". | number | |
| maxLength | max-length | When the component resides in a form,
specifies the maximum length of text for the component's value. | number | |
| messageOverrides | Overrides individual strings used by the component. | Record<string, unknown> | undefined | ||
| min | min | When the component resides in a form,
specifies the minimum value for type="number". | number | |
| minLength | min-length | When the component resides in a form,
specifies the minimum length of text for the component's value. | number | |
| multiple | multiple | When true and type is "email" or "file", the component can accept more than one value.
Read the native attribute's documentation on MDN for more info. | boolean | false |
| name | name | Specifies the name of the component.
Required to pass the component's value on form submission. | string | |
| numberButtonType | number-button-type | When type="number", specifies the placement of the buttons. | InputPlacement | "vertical" |
| numberingSystem | numbering-system | Specifies the Unicode numeral system used by the component for localization. | NumberingSystem | |
| pattern | pattern | When the component resides in a form,
specifies a regular expression (regex) pattern the component's value must match for validation.
Read the native attribute's documentation on MDN for more info. | string | |
| placeholder | placeholder | Specifies the component's placeholder text. | string | |
| prefixText | prefix-text | Specifies text to display at the start of the component. | string | |
| readOnly | read-only | When true, the component's value can be read, but cannot be modified. | boolean | false |
| required | required | When true and the component resides in a form,
the component must have a value in order for the form to submit. | boolean | false |
| scale | scale | Specifies the size of the component. | Scale | "m" |
| status | status | Specifies the input field's status, which determines message and icons. | Status | "idle" |
| step | step | Specifies the granularity the component's value must adhere to. | number | "any" | |
| suffixText | suffix-text | Specifies text to display at the end of the component. | string | |
| type | type | Specifies the component type.
Note that the following types add type-specific icons by default: "date", "email", "password", "search", "tel", "time". | "color" | "date" | "datetime-local" | "email" | "file" | "image" | "month" | "number" | "password" | "search" | "tel" | "text" | "time" | "url" | "week" | "text" |
| validationIcon | validation-icon | Specifies the validation icon to display under the component. | IconName | boolean | |
| validationMessage | validation-message | Specifies the validation message to display under the component. | string | |
| validity | The component's current validation state. | MutableValidityState | ||
| value | value | The component's value. | string |
Slots
| Name | Description |
|---|---|
| action | A slot for positioning a calcite-action or other interactive content adjacent to the component. |
| label-content | A slot for rendering content next to the component's labelText. |
Styles
| Name | Description |
|---|---|
| --calcite-input-prefix-size | When prefixText is provided, specifies the width of the component's prefix element. |
| --calcite-input-suffix-size | When suffixText is provided, specifies the width of the component's suffix element. |
| --calcite-input-prefix-text-color | When prefixText is provided, specifies the text color of the component's prefix element. |
| --calcite-input-suffix-text-color | When suffixText is provided, specifies the text color of the component's suffix element. |
| --calcite-input-background-color | Specifies the component's background color. |
| --calcite-input-border-color | Specifies the component's border color. |
| --calcite-input-corner-radius | Specifies the component's corner radius. |
| --calcite-input-shadow | Specifies the component's shadow. |
| --calcite-input-icon-color | Specifies the component's icon color. |
| --calcite-input-text-color | Specifies the component's text color. |
| --calcite-input-placeholder-text-color | Specifies the component's placeholder text color. |
| --calcite-input-actions-background-color | Specifies the background color of the component's clearable and number-button-type elements. |
| --calcite-input-actions-background-color-hover | Specifies the background color of the component's clearable and number-button-type elements when hovered. |
| --calcite-input-actions-background-color-press | Specifies the background color of the component's clearable and number-button-type elements when pressed. |
| --calcite-input-actions-icon-color | Specifies the icon color of the component's clearable and number-button-type elements. |
| --calcite-input-actions-icon-color-hover | Specifies the icon color of the component's clearable and number-button-type elements when hovered. |
| --calcite-input-actions-icon-color-press | Specifies the icon color of the component's clearable and number-button-type elements when pressed. |
| --calcite-input-loading-background-color | When loading, specifies the background color of the component's loading element. |
| --calcite-input-loading-fill-color | When loading, specifies the fill color of the component's loading element. |
Events
| Name | Description | Behavior |
|---|---|---|
| calciteInputChange | Fires each time a new value is typed and committed. | |
| calciteInputInput | Fires each time a new value is typed. |
Methods
| Name | Description | Signature |
|---|---|---|
| componentOnReady | Create a promise that resolves once component is fully loaded. | componentOnReady(): Promise<this> |
| selectText | Selects the text of the component's value. | selectText(): Promise<void> |
| setFocus | Sets focus on the component. | setFocus(options?: FocusOptions): Promise<void> |