-
Notifications
You must be signed in to change notification settings - Fork 6
File Input Specification
Simeon Simeonoff edited this page Mar 26, 2025
·
2 revisions
Team Name: Product Design Team
Developer: Simeon Simeonoff
Designer: Svilen Dimchevski
- Radoslav Karaivanov | Date:
- Product Owner: Radoslav Mirchev | Date:
- Platform Architect: Radoslav Karaivanov | Date:
| Version | Author | Date | Notes |
|---|---|---|---|
| 1 | Simeon Simeonoff | 26-March-2025 | Initial draft |
The igc-file-input component provides an interactive way for users to select and upload files. It extends the base input functionality while adding file-specific features such as file selection, displaying selected file names, and handling multiple file uploads.
Developer:
- As a developer, I want to add a file input component to allow users to upload files in my application.
- As a developer, I want to be able to provide a name so that the file input field is identifiable in the context of a web form.
- As a developer, I want to be able to set multiple attribute so that I can allow users to select more than one file.
- As a developer, I want to be able to set accept attribute to restrict what file types can be uploaded.
- As a developer, I want to add a required attribute so that the file input field becomes mandatory.
- As a developer, I want to be able to set the file input as disabled so that the input field value couldn't be modified or interacted with.
- As a developer, I want to access the selected files so that I can process them in my application.
- 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 that displays when no file is chosen.
- 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 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, hover, press, focus, error, disabled, valid/invalid) applied to all file input parts so that the user would know the state of the input and act accordingly.
- As a developer, I want to be able to customize the browse button text through slotting.
- As a developer, I want to be able to customize the "No file chosen" text through slotting.
- As a developer, I want to be able to handle when users cancel the file selection dialog.
End user:
- As an end user, I want to select files from my device to upload them to a web application.
- As an end user, I want to see which files I have selected.
- As an end user, I want to be able to select multiple files when needed.
- As an end user, I want to have a visual indicator, such as outline so that I will know which file 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 file input field.
- As an end user, I want to have a label so that I can identify the file input.
- As an end user, I want to have see helper text so that I get updates about my input such as validation messages.
- As an end user, I want to have an asterisk glyph in the label so that I would know that the file input is required.
- As an end user, I want to have prefix and/or suffix in the file input so that I would have more context.
A file input allows users to select files from their device and upload them to a web application. It displays the names of selected files and provides customization options for the browse button and "No file chosen" text.
3.1 API
You should be able to configure the igc-file-input by setting its properties:
| Name | Description | Type | Default value | Reflected |
|---|---|---|---|---|
name |
Sets the name of the file input field. | string | - | false |
disabled |
Sets the disabled state of the file input field. | Boolean | false |
true |
required |
Sets the required state of the file input field. | Boolean | false |
true |
invalid |
Sets the validity of the file input. | Boolean | false |
true |
multiple |
Allows selection of more than one file. | Boolean | false |
false |
accept |
Sets the file types as a list of comma-separated values. | string | - |
false |
autofocus |
Automatically focuses the file input on page load. | Boolean | false |
false |
files |
Returns the selected files when input type is 'file'. | FileList / null | null |
false |
label |
Sets the label of the file input field. | string | - |
false |
placeholder |
Sets the placeholder text when no file is chosen. | string | - |
false |
The igc-file-input emits the following events:
| Name | Description | Type |
|---|---|---|
igcFocus |
Emitted when the file input field gains focus. | - |
igcBlur |
Emitted when the file input field loses focus. | - |
igcChange |
Emitted when the file input field changes its state. | detail: value |
igcInput |
Emitted when the file input field receives input. | detail: value |
igcCancel |
Emitted when the file picker dialog is canceled. | detail: { message: string, value: string } |
The igc-file-input inherits methods from the IgcInputBaseComponent:
| Name | Description | Arguments |
|---|---|---|
focus |
Sets the file input on focus. | options: FocusOptions |
blur |
Removes the focus from the file 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 |
| Name | Description |
|---|---|
| prefix | The prefix slot. |
| suffix | The suffix slot. |
| helper-text | The helper-text slot. |
| file-selector-text | Renders content for the browse button when input type is file. |
| file-missing-text | Renders content when input type is file and no file is chosen. |
| value-missing | Renders content when the required validation fails. |
| custom-error | Renders content when setCustomValidity(message) is set. |
| invalid | Renders content when the component is in invalid state (validity.valid = false). |
| Name | Description |
|---|---|
| container | The main wrapper that holds all main input elements. |
| input | The native input element. |
| label | The native label element. |
| file-names | The file names wrapper. |
| file-selector-button | The browse button. |
| prefix | The prefix wrapper. |
| suffix | The suffix wrapper. |
| helper-text | The helper text wrapper. |
The encapsulated native file input is the de facto focusable and interactive element. The file input can be labeled using the label attribute, which utilizes the native <label> element to provide a semantically correct label that is fully accessible.
The component uses proper ARIA attributes for invalid states and helper text connections:
-
aria-invalid: Set to 'true' when the input is invalid -
aria-describedby: Connected to the helper text when present
- Have file input that is focusable.
- Handle events like blur, focus, change, input, and cancel.
- Allow file selection and display selected file names.
- Support multiple file selection.
- Support file type filtering via the accept attribute.
- Provide label, hint text, placeholder.
- Allow customization of browse button text and "No file chosen" text.
- Corresponding styles, animations and interactions.