Input | Calcite Design System

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.

Sample

Usage

Text or number entries
Any type of entry tied to validation
Data entry
Form elements

Accessibility

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 component`s` 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 `type`s 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`
validityread-only		The component's current validation state.	`ValidityState`
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.	bubblescomposed
calciteInputInput	Fires each time a new `value` is typed.	bubblescomposedcancelable

Methods

Name	Description	Signature
componentOnReady	Creates a promise that resolves once the 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>`