Skip to content

Commit 728b38e

Browse files
simeonoffsimeonoff
authored
Merge pull request #1487 from IgniteUI/apetrov/add-file-input-docs-vnext
docs(file-input): add file input topic (vnext)
2 parents d593eba + 8240546 commit 728b38e

2 files changed

Lines changed: 172 additions & 0 deletions

File tree

‎doc/en/components/inputs/file-input.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
---
2+
title: {Platform} File Input | Data Visualization Tools | Infragistics
3+
_description: Infragistics' {Platform} File input is a component where the user can select and upload files. Improve your application with {ProductName}!
4+
_keywords: {Platform} File input, {ProductName}, Infragistics
5+
mentionedTypes: ["Input", "Icon", "Button"]
6+
---
7+
# {Platform} File Input Overview
8+
9+
The {ProductName} File Input component provides an interactive way for users to select and upload files. It extends the base `Input` functionality by adding file-specific features such as file selection, displaying selected file names, and supporting multiple file uploads.
10+
11+
## {Platform} File Input Example
12+
13+
<div class="divider--half"></div>
14+
15+
`sample="/inputs/file-input/overview", height="120", alt="{Platform} File Input Overview Example"`
16+
17+
## Usage
18+
19+
The File Input component allows users to select files from their device and upload them to a web application. It displays the names of selected files and offers customization options for the browse button and the "No file chosen" text. The component also provides properties, methods, and slots that can be used to further configure its behavior to suit your needs.
20+
21+
### Getting Started
22+
23+
<!-- WebComponents -->
24+
25+
To start using the File Input, first, you need to install the Ignite UI for Web Components by running the following command:
26+
27+
```cmd
28+
npm install {PackageWebComponents}
29+
```
30+
31+
After that, you need to import the File Input as follows:
32+
33+
```ts
34+
import { defineComponents, IgcFileInputComponent } from 'igniteui-webcomponents';
35+
36+
defineComponents(IgcFileInputComponent);
37+
```
38+
39+
<!-- end: WebComponents -->
40+
41+
Now you can start with a basic configuration of the {Platform} File Input.
42+
43+
```html
44+
<igc-file-input label="File Input" required=true></igc-file-input>
45+
```
46+
47+
For a complete introduction to the {ProductName}, read the [*Getting Started*](../general-getting-started.md) topic.
48+
49+
## Configuration
50+
51+
### Properties
52+
53+
The File Input component offers a variety of properties that allow you to configure its behavior based on specific requirements. These properties give you control over the input’s functionality, appearance, and validation.
54+
55+
* `value` - Sets the current value of the file input field.
56+
* `disabled` - Disables the file input, preventing user interaction.
57+
* `required` - Marks the input as mandatory. Form submission will be blocked unless a file is selected.
58+
* `invalid` - Indicates that the input value is invalid, used to trigger visual error states.
59+
* `multiple` - Allows the selection of multiple files.
60+
* `accept` - Defines the types of files that can be selected. The value for this property needs to be a comma-separated list of file formats (e.g., .jpg, .png, .gif).
61+
* `autofocus` - Automatically focuses the file input field when the page loads.
62+
* `label` - Sets the label text associated with the file input element.
63+
* `placeholder` - Provides placeholder text displayed when no file is selected.
64+
65+
```html
66+
<igc-file-input
67+
label="Files Input"
68+
accept=".jpg, .png, .gif"
69+
placeholder="Files missing"
70+
required
71+
multiple>
72+
</igc-file-input>
73+
```
74+
75+
### Methods
76+
77+
In addition to its configurable properties, the File Input component also inherits four useful methods from the `Input` component that you can use:
78+
79+
* `focus()` - Sets the focus on the file input element.
80+
* `blur()` - Removes the focus from the file input element.
81+
* `reportValidity()` - Checks the validity of the input and displays a validation message if the input is invalid.
82+
* `setCustomValidity()` - Sets a custom validation message. If the provided message is not empty, the input will be marked as invalid.
83+
84+
### Slots
85+
86+
The File Input component also exposes several slots that can be used to customize its appearance and behavior.
87+
88+
* `prefix` & `suffix` - Allow you to insert content before or after the main input area.
89+
* `helper-text` - Displays a hint or instructional message below the input. Useful for providing additional guidance, such as formatting tips or field requirements.
90+
* `file-selector-text` - Allow you to customizes the text displayed on the file selection button.
91+
* `file-missing-text` - Sets the text shown in the input field when no file has been selected.
92+
* `value-missing` - Renders custom content when the required field validation fails. (i.e., when a file is required but not provided).
93+
* `invalid` – Allows you to render custom content when the input is in an invalid state.
94+
* `custom-error` - Displays content when a custom validation message is set using the `setCustomValidity()` method.
95+
96+
`sample="/inputs/file-input/prefix-suffix", height="120", alt="{Platform} File Input Slots Example"`
97+
98+
## Integration
99+
100+
The File Input component integrates seamlessly with the HTML Form element. Using the methods and properties described above, you can effectively manage its behavior and validation within the standard HTML Forms.
101+
102+
`sample="/inputs/file-input/form", height="190", alt="{Platform} File Input Form Example"`
103+
104+
## Limitations
105+
106+
The File Input component currently has the following limitations:
107+
- The default strings for the "Browse" button and the "No file chosen" message is not automatically localized. These strings remain the same across all locales but can be manually customized using the appropriate slots or placeholder binding.
108+
- Files cannot be set manually through the `value` property. File selection can be done only via the file picker. You can however pass an empty string `''` to reset the field.
109+
110+
## Accessibility & ARIA Support
111+
112+
The File Input component is both focusable and interactive, ensuring full keyboard and screen reader accessibility. The component can be labeled using the `label` attribute, which leverages the native `<label>` element to provide a semantically correct and accessible label.
113+
114+
To support accessibility best practices, the component also applies relevant ARIA attributes:
115+
116+
* `aria-invalid` - Set to "true" when the input is in an invalid state.
117+
* `aria-describedby` - Automatically linked to the helper text element when present, allowing assistive technologies to announce the additional information.
118+
119+
## Styling
120+
121+
The `File Input` component exposes CSS parts which we can use for styling. The following table lists all of the exposed CSS parts:
122+
123+
|Name|Description|
124+
|--|--|
125+
| `container` | The main wrapper that holds all main input elements. |
126+
| `input` | The native input element. |
127+
| `label` | The native label element. |
128+
| `file-names` | The file names wrapper. |
129+
| `file-selector-button` | The browse button. |
130+
| `prefix` | The prefix wrapper. |
131+
| `suffix` | The suffix wrapper. |
132+
| `helper-text` | The helper text wrapper. |
133+
134+
135+
```scss
136+
igc-file-input::part(file-names) {
137+
background-color: var(--ig-primary-50);
138+
color: var(--ig-gray-400);
139+
}
140+
141+
igc-file-input::part(suffix) {
142+
color: var(--ig-primary-700-contrast);
143+
background-color: var(--ig-primary-700);
144+
}
145+
146+
igc-file-input::part(label) {
147+
color: var(--ig-gray-600);
148+
}
149+
```
150+
151+
`sample="/inputs/file-input/styling", height="120", alt="{Platform} File Input Styling"`
152+
153+
<div class="divider"></div>
154+
155+
156+
## API References
157+
158+
- `Icon`
159+
- `Input`
160+
- `Button`
161+
- [`Styling & Themes`](../themes/overview.md)
162+
163+
## Additional Resources
164+
165+
* [{ProductName} **Forums**]({ForumsLink})
166+
* [{ProductName} **GitHub**]({GithubLink})

‎docfx/en/components/toc.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1720,6 +1720,12 @@
17201720
"name": "Input",
17211721
"href": "inputs/input.md"
17221722
},
1723+
{
1724+
"exclude": ["Angular", "React", "Blazor"],
1725+
"name": "File Input",
1726+
"href": "inputs/file-input.md",
1727+
"status": "new"
1728+
},
17231729
{
17241730
"exclude": ["Angular", "Blazor"],
17251731
"name": "Mask Input",

0 commit comments

Comments
 (0)