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 type
s, 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
<calcite-input placeholder="Enter your region"></calcite-input>
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 | Specifies a comma separated list of unique file type specifiers for limiting accepted file types.
This property only has an effect when type is "file".
Read the native attribute's documentation on MDN for more info. | string | |
alignment | alignment | Specifies the text alignment of the component's value. | "end" | "start" | "start" |
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 , a clear button is displayed when the component has a value. The clear button shows by default for "search" , "time" , and "date" types, and will not display for the "textarea" type. | boolean | false |
disabled | disabled | When true , interaction is prevented and the component is displayed with lower opacity. | boolean | false |
files | When type is "file" , specifies the component's selected files. | FileList | ||
form | form | The id of the form that will be associated with the component.
When not set, the component will be associated with its ancestor form element, if any. | 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 , shows a default recommended icon. Alternatively, pass a Calcite UI Icon name to display a specific icon. | boolean | string | |
iconFlipRtl | icon-flip-rtl | When true , the icon will be flipped when the element direction is right-to-left ("rtl" ). | boolean | false |
label | label | Accessible name for the component. | 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 | Use this property to override individual strings used by the component. | {
clear?: string;
loading?: string;
} | ||
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 , the component can accept more than one value.
This property only has an effect when type is "email" or "file".
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 | Specifies the placement of the buttons for type="number" . | "horizontal" | "none" | "vertical" | "vertical" |
numberingSystem | numbering-system | Specifies the Unicode numeral system used by the component for localization. | "arab" | "arabext" | "latn" | |
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 placeholder text for the component. | string | |
prefixText | prefix-text | Adds text to 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. | "l" | "m" | "s" | "m" |
status | status | Specifies the status of the input field, which determines message and icons. | "idle" | "invalid" | "valid" | "idle" |
step | step | Specifies the granularity the component's value must adhere to. | "any" | number | |
suffixText | suffix-text | Adds text to 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" .
"textarea" [Deprecated] use the calcite-text-area component instead. | "color" | "date" | "datetime-local" | "email" | "file" | "image" | "month" | "number" | "password" | "search" | "tel" | "text" | "textarea" | "time" | "url" | "week" | "text" |
validationIcon | validation-icon | Specifies the validation icon to display under the component. | boolean | string | |
validationMessage | validation-message | Specifies the validation message to display under the component. | string | |
validity | The current validation state of the component. | {
valid: boolean;
badInput: boolean;
customError: boolean;
patternMismatch: boolean;
rangeOverflow: boolean;
rangeUnderflow: boolean;
stepMismatch: boolean;
tooLong: boolean;
tooShort: boolean;
typeMismatch: boolean;
valueMissing: boolean;
} | ||
value | value | The component's value. | string |
Slots
Name | Description |
---|---|
action | A slot for positioning a calcite-button next to the component. |
Styles
Name | Description |
---|---|
--calcite-input-prefix-size | Specifies the component's prefix width, when present. |
--calcite-input-suffix-size | Specifies the component's suffix width, when present. |
--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 shadow around the component. |
--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 | Specifies the background color of the loading element, when present. |
--calcite-input-loading-fill-color | Specifies the fill color of the loading element, when present. |
--calcite-input-prefix-background-color | Specifies the component's prefix background color, when present. |
--calcite-input-prefix-text-color | Specifies the component's prefix text color, when present. |
--calcite-input-suffix-background-color | Specifies the component's suffix background color, when present. |
--calcite-input-suffix-text-color | Specifies the component's suffix text color, when present. |
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<void> |
selectText | Selects the text of the component's value . | selectText(): Promise<void> |
setFocus | Sets focus on the component. | setFocus(): Promise<void> |