Input Specification - IgniteUI/igniteui-webcomponents GitHub Wiki
The igc-input component provides an interactive way to accept data from the user; It supports wide variety of data types. The igc-input is one of the most robust and powerful components due to the complex combination of data types and attributes it supports.
Developer:
- As a developer, I want to add an input of different HTML input types(date, datetime-local, email, month, number, password, search, tel, text, time, url, week) so that the user can enter different types of information in the app.
- As a developer, I want to be able to provide a name so that the input field is identifiable in the context of a web form.
- As a developer, I want to be able to set a value so that the input field can be programmatically initialized or updated.
- As a developer, I want to be able to set min so that I can restrict the minimum value of the input.
- As a developer, I want to be able to set max so that I can restrict the maximum value of the input.
- As a developer, I want to be able to set minlength so that I can restrict the minimum length of the input value.
- As a developer, I want to be able to set maxlength so that I can restrict the maximum length of the input value.
- As a developer, I want to add a required attribute so that the input field becomes mandatory.
- As a developer, I want to be able to set the input as disabled so that the input field value couldn't be modified or interacted with.
- As a developer, I want to be able to set the input as readonly so that the input field value couldn't be modified but can still be focusable and/or interacted with.
- As a developer, I want to be able to provide a pattern so that the input field value can be validated against specific criteria.
- As a developer, I want to be able to set the input as invalid so that I can deterministically mark a field as invalid.
- As a developer, I want to be able to set the autocomplete attribute so that the field can suggest previously entered values like emails, phone numbers, passwords, etc.
- As a developer, I want to be able to set the step attribute so that numeric fields can be incremented by a specified amount.
- As a developer, I want to be able to set the autofocus attribute so that the field can become focused on initial page load.
- As a developer, I want to add a label so that the user would know what to enter and easily differentiate between several inputs placed on the same page.
- As a developer, I want to add a placeholder so that the user has an example of the expected input value. A placeholder can be used without or with a label.
- As a developer, I want to add a prefix and/or suffix content so that I can make compound, padded input fields comprised of icons and text.
- As a developer, I want to add a helper text (left or/and right aligned) so that the user would have more details and updates (hints/errors) about this field.
- As a developer, I want to have states and corresponding design styles (enabled: idle & empty, hover, press, focus, idle & filled, error, disabled, read-only, valid/invalid, empty/filled) applied to all input parts (label, placeholder, helper text, prefix, suffix, etc.) so that the user would know the state of the input and act accordingly.
- As a developer, I want to be able to make the prefix and suffix actionable so that the user can further interact with them.
- As a developer, I want to be able to programmatically select all or some characters of the input value so that I can extract the exact information I need based on the constraints I have.
- As a developer, I want to be able to alter between
filledandoutlinedstyles for material-styled inputs so that I can have differently styled material inputs.
End user:
- As an end user, I want to enter characters in a field so that I can provide data to a web form or other parts of an application.
- As an end user, I want to have a visual indicator, such as outline so that I will know which input field is currently on focus.
- As an end user, I want to have different visual states so that I know how to interact with the input field.
- As an end user, I want to have a label so that I can identify the input.
- As an end user, I want to have see helper text so that I get updates about my input such as counters, error/success messages, etc.
- As an end user, I want to have an asterisk glyph in the label so that I would know that the input is required.
- As an end user, I want to have prefix and/or suffix in the input so that I would have more context.
- As an end user, I want to have the actionable prefix and/or suffix in the input so that I can perform quick action on the input (example: clear input suffix icon).
An input is a text field where users enter specific information of different data types. The inputs can be validated. Helper text, placeholders, and visual states can be updated accordingly upon string input/interaction and data can be submitted.
3.1 API
You should be able to configure the igc-input by setting its properties:
| Name | Description | Type | Default value | Reflected |
|---|---|---|---|---|
name |
Sets the name of the input field. | string | - | false |
value |
Sets the value of the input field. | string | - | false |
type |
Sets the checked state of the type of the input field. | 'email', 'number', 'password', 'search', 'tel', 'text', 'url' | text |
false |
disabled |
Sets the disabled state of the input field. | Boolean | false |
true |
readonly |
Sets the input field as read-only. | Boolean | false |
true |
required |
Sets the required state of the input field. | Boolean | false |
true |
invalid |
Sets the validity of the input. | Boolean | false |
true |
pattern |
Pattern to validate the input against. | string | - |
false |
minlength |
The minimum length of the input value. | number | - |
false |
maxlength |
The maximum length of the input value. | number | - |
false |
min |
The minimum value of the input. | string / number | - |
false |
max |
The maximum value of the input. | string / number | - |
false |
step |
Increments the input by the specified value. | number | - |
false |
autocomplete |
The autocomplete attribute of the input. | string | - |
false |
autofocus |
Automatically focuses the input on page load. | Boolean | false |
false |
label |
Sets the label of the input field. | string | - |
false |
placeholder |
Sets the placeholder of the input field. | string | - |
false |
outlined |
Sets material-themed inputs to outlined style mode. | Boolean | false |
true |
validateOnly |
Enables validation rules to be evaluated without restricting user input. This applies to the maxLength property for string-type inputs or allows spin buttons to exceed the predefined min/max limits for number-type inputs. |
boolean | false |
true |
The igc-input emits the following events:
| Name | Description | Type |
|---|---|---|
igcFocus |
Emitted when the input field gains focus. | - |
igcBlur |
Emitted when the input field loses focus. | - |
igcChange |
Emitted when the input field changes its checked state. | - |
igcInput |
Emitted when the input field receives input. | - |
The igc-input exposes the following methods:
| Name | Description | Arguments |
|---|---|---|
focus |
Sets the input on focus. | options: FocusOptions |
blur |
Removes the focus from the input | - |
reportValidity |
Checks for validity and shows a validation message if the component is invalid. | - |
setCustomValidity |
Sets a custom validation message. If the message is not empty, the field will be considered invalid. | message: string |
select |
Select all text in the input. | - |
setRangeText |
Replaces the selected range of text with a new value. | - |
setSelectionRange |
Sets the start and end position of the text selection. | selectionStart: number, selectionEnd: number, [selectionDirection] |
stepUp |
Increments the value of a numeric input by one or by the specified number of units. | - |
stepDown |
Decrements the value of a numeric input by one or by the specified number of units. | - |
| Name | Description |
|---|---|
| prefix | The prefix slot. |
| suffix | The suffix slot. |
| helper-text | The helper-text slot. |
| Name | Description |
|---|---|
| input | The native input. |
| label | The native label. |
| prefix | The prefix container. |
| suffix | The suffix container. |
The encapsulated native input is the de facto focusable and interactive element. The input can be labeled using the label attribute, which utilizes the native <label> element to provide a semantically correct label that is fully accessible.
- Have input that is focusable.
- Handle events like blur, focus, change, and input.
- Have input that provides a way to type characters.
- Have prefix**/-input/**-suffix options.
- Provide label, hint text, placeholder.
- Corresponding styles, animations and interactions (as per the material design guidelines).
https://material.io/guidelines/components/text-fields.html#text-fields-field-variations https://material.angular.io/components/input/overview https://codepen.io/simeonoff/pen/dmyQqw