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 \| undefined`
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 \| undefined`
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 \| undefined`
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 \| undefined`
iconFlipRtl	icon-flip-rtl	When `true` and the element direction is right-to-left (`"rtl"`), flips the component`s` icon`.	`boolean`	`false`
inlineEdit	inline-edit	Enables inline editing. When not editing, the component displays without a border. When `true`, edits must be saved or cancelled via controls. When `"controls-disabled"` is specified, edits are saved on blur.	`boolean \| "controls-disabled"`	`false`
inlineEditing	inline-editing	When `true` and `inlineEdit` is defined, the component is editable.	`boolean`	`false`
inlineEditingBeforeConfirm		When `inlineEdit` is `true`, specifies a callback to be run when changes are saved.	`(() => Promise<void>) \| undefined`
label	label	Specifies an accessible label for the component.	`string \| undefined`
labelText	label-text	Specifies the component's label text.	`string \| undefined`
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 \| undefined`
maxLength	max-length	When the component resides in a form, specifies the maximum length of text for the component's `value`.	`number \| undefined`
messageOverrides		Replace localized message strings with your own strings. Note: Individual message keys may change between releases.	`Record<string, unknown> \| undefined`
min	min	When the component resides in a form, specifies the minimum value for `type="number"`.	`number \| undefined`
minLength	min-length	When the component resides in a form, specifies the minimum length of text for the component's `value`.	`number \| undefined`
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 \| undefined`
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 \| undefined`
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 \| undefined`
placeholder	placeholder	Specifies the component's placeholder text.	`string \| undefined`
prefixText	prefix-text	Specifies text to display at the start of the component.	`string \| undefined`
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" \| undefined`
suffixText	suffix-text	Specifies text to display at the end of the component.	`string \| undefined`
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 \| undefined`
validationMessage	validation-message	Specifies the validation message to display under the component.	`string \| undefined`
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.
--calcite-input-inline-edit-background-color-hover	When `inlineEdit` is defined and `inlineEditing` is not set, specifies the component's background color when hovered.
--calcite-input-inline-edit-control-background-color	When `inlineEdit` is defined, specifies the background color of the component's editing controls.
--calcite-input-inline-edit-control-background-color-hover	When `inlineEdit` is defined, specifies the background color of the component's editing controls when hovered.
--calcite-input-inline-edit-control-background-color-press	When `inlineEdit` is defined, specifies the background color of the component's editing controls when pressed.
--calcite-input-inline-edit-control-corner-radius	When `inlineEdit` is defined, specifies the corner radius of the component's editing controls.
--calcite-input-inline-edit-control-loader-color	When `inlineEdit` is `true`, specifies the loader color of the component's confirm control.
--calcite-input-inline-edit-control-text-color	When `inlineEdit` is defined, specifies the text color of the component's editing controls.
--calcite-input-inline-edit-control-text-color-press	When `inlineEdit` is defined, specifies the text color of the component's editing controls when pressed or hovered.

Events

Name	Description	Behavior
calciteInputChange	Fires each time a new `value` is committed.	bubblescomposed
calciteInputInlineEditingCancel	When `inlineEdit` is defined, fires when editing is cancelled.	bubblescomposed
calciteInputInlineEditingChange	When `inlineEdit` is defined, fires when `inlineEditing` is enabled or disabled.	bubblescomposed
calciteInputInlineEditingConfirm	When `inlineEdit` is `true`, fires after editing is confirmed.	bubblescomposed
calciteInputInput	When `inlineEdit` is `false`, 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>`