Inputs are text containers which can be used to create forms, enter data, and enact various commands.

Overview

Input is an extremely robust component designed to fill many needs throughout an interface, supporting prefixes, suffixes, clear controls, icons, and buttons. Input also supports an error state where a validationMessage can be used to provide feedback when its value is invalid.

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

Best practices

Input alternatives

Input supports several HTML input type values. When using the following type values, evaluate the use of alternative components for tailored functionality and validation.

Input typeRecommended component implementation
"date"Input Date Picker
"number"Input Number
"text"Input Text
"time"Input Time Picker

Validation

Use validationMessage to provide guidance when an Input's status is "invalid". The validationMessage should explain how to fix the error and avoid generic messages such as “invalid value.”

Cell phone number Input in an invalid state with a validation message stating that phone numbers must be 10 digits. The Input only has 9 digits.
Do use validationMessage to give users clear, actionable guidance when a value is invalid.
Cell phone number Input in an invalid state with a validation message stating that it is an incorrect entry.
Avoid using a vague validationMessage that doesn't give users enough context to correct the error.

Inline Edit

Recent bear sightings map with a title is using an Input with the inline-edit property.
Do consider using inlineEdit for content that can have a text change after being submitted, such as a title or heading.
Form to document bear sightings where the Location and Number of bears observed fields are using an Input with the inline-edit property. Location is actively being edited.
Avoid using inlineEdit in a form.

Accessibility

Keyboard navigation

KeyFunction
TabMoves focus in and out of the component.
Tab and ShiftMoves focus in and out of the component.
EscIf the component is focused and clearable with a value - will clear the value.

API reference

Properties

PropertyAttributeDescriptionTypeDefault
acceptaccept

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
alignmentalignment

Specifies the text alignment of the component's value.

Extract<"start" | "end", Alignment>"start"
autocompleteautocomplete

Specifies the type of content to autocomplete, for use in forms. Read the native attribute's documentation on MDN for more info.

AutoFill | undefined
clearableclearable

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.

booleanfalse
disableddisabled

When true, prevents interaction and decreases the component's opacity.

booleanfalse
files

When type is "file", specifies the component's selected files.

FileList | undefined
formform

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
groupSeparatorgroup-separator

When true, number values are displayed with a group separator corresponding to the language and country format.

booleanfalse
iconicon

When true, displays a default recommended icon. Alternatively, pass a Calcite UI Icon name to display a specific icon.

IconName | boolean | undefined
iconFlipRtlicon-flip-rtl

When true and the element direction is right-to-left ("rtl"), flips the components icon`.

booleanfalse
inlineEditinline-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
inlineEditinginline-editing

When true and inlineEdit is defined, the component is editable.

booleanfalse
inlineEditingBeforeConfirm

When inlineEdit is true, specifies a callback to be run when changes are saved.

(() => Promise<void>) | undefined
labellabel

Specifies an accessible label for the component.

string | undefined
labelTextlabel-text

Specifies the component's label text.

string | undefined
loadingloading

When true, a busy indicator is displayed.

booleanfalse
maxmax

When the component resides in a form, specifies the maximum value for type="number".

number | undefined
maxLengthmax-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
minmin

When the component resides in a form, specifies the minimum value for type="number".

number | undefined
minLengthmin-length

When the component resides in a form, specifies the minimum length of text for the component's value.

number | undefined
multiplemultiple

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.

booleanfalse
namename

Specifies the name of the component.

Required to pass the component's value on form submission.

string | undefined
numberButtonTypenumber-button-type

When type="number", specifies the placement of the buttons.

InputPlacement"vertical"
numberingSystemnumbering-system

Specifies the Unicode numeral system used by the component for localization.

NumberingSystem | undefined
patternpattern

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
placeholderplaceholder

Specifies the component's placeholder text.

string | undefined
prefixTextprefix-text

Specifies text to display at the start of the component.

string | undefined
readOnlyread-only

When true, the component's value can be read, but cannot be modified.

booleanfalse
requiredrequired

When true and the component resides in a form, the component must have a value in order for the form to submit.

booleanfalse
scalescale

Specifies the size of the component.

Scale"m"
statusstatus

Specifies the input field's status, which determines message and icons.

Status"idle"
stepstep

Specifies the granularity the component's value must adhere to.

number | "any" | undefined
suffixTextsuffix-text

Specifies text to display at the end of the component.

string | undefined
typetype

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"
validationIconvalidation-icon

Specifies the validation icon to display under the component.

IconName | boolean | undefined
validationMessagevalidation-message

Specifies the validation message to display under the component.

string | undefined
validityread-only

The component's current validation state.

ValidityState
valuevalue

The component's value.

string

Slots

NameDescription
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

NameDescription
--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

NameDescriptionBehavior
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

NameDescriptionSignature
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>

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.