---
title: "File input"
description: "A file input is used to choose and upload files."
url: https://developers.dhis2.org/docs/ui/components/fileinput
source: https://github.com/dhis2/developer-portal/edit/main/docs/ui/components/fileinput.md
---

# File input

A file input is used to choose and upload files.

[Interactive demo: file-input-field--with-label](https://developers.dhis2.org/demo/?path=/story/file-input-field--with-label)

## Usage

### When to use

- **Adding files from a user's machine**. Use a file input when a user can upload a file from their local machine. This is usually as part of a form.

### When not to use

- **Adding files that exist elsewhere**. Don't use a file input if a user is choosing files from somewhere else than their local machine, like files already uploaded to an app.

### Format

#### Content

##### Label

[Interactive demo: file-input-field--with-label](https://developers.dhis2.org/demo/?path=/story/file-input-field--with-label)

```jsx
<FileInputField label="Upload birth certificate" />
```

- Use a label above the button if the file input is part of a form with other controls.

##### Button

[Interactive demo: file-input-field--with-label](https://developers.dhis2.org/demo/?path=/story/file-input-field--with-label)

```jsx
<FileInputField buttonLabel="Upload test data" />
```

- When a form label isn't used, the button label should make it clear what kind of file is expected. Use _Upload certificate_ instead of just _Upload_, for example.

##### Help text

[Interactive demo: file-input-field--help-text](https://developers.dhis2.org/demo/?path=/story/file-input-field--help-text)

```jsx
<FileInputField helpText="Max size 5mb" label="Upload birth certificate" />
```

- Use help text to tell the user about any limitations or expectations of the files, like size or format.

## Options

### Multiple files

[Interactive demo: file-input-field--file-list](https://developers.dhis2.org/demo/?path=/story/file-input-field--file-list)

```jsx
<FileInputField label="Upload documents">
    <FileListItem label="picture1.jpg" removeText="Remove" />
    <FileListItem
        label="mage_that_is_uploading.jpg"
        loading
        cancelText="Cancel"
    />
    <FileListItem
        label="image_file_name_is_to_long_to_display_on_one_line.jpg"
        removeText="Remove"
    />
</FileInputField>
```

- Allow multiple file upload if that fits the use case.
- Don't use several file inputs for the same kind of file, use one with multiple files allowed.

## API Reference

### FileInput

#### Usage

To use `FileInput`, you can import the component from the `@dhis2/ui` library  

```js
import { FileInput } from '@dhis2/ui'
```

#### Props

|Name|Type|Default|Required|Description|
|---|---|---|---|---|
|accept|string|``'*'``||The `accept` attribute of the [native file input](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#accept)|
|buttonLabel|string||||
|className|string||||
|dataTest|string|``'dhis2-uicore-fileinput'``|||
|disabled|boolean||||
|error|custom|||Input status. Mutually exclusive with `warning` and `valid`|
|initialFocus|boolean||||
|large|custom|||Button size. Mutually exclusive with `small`|
|multiple|boolean|||The `multiple` attribute of the [native file input](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#multiple)|
|name|string||||
|small|custom|||Button size. Mutually exclusive with `large`|
|tabIndex|string||||
|valid|custom|||Input status. Mutually exclusive with `warning` and `error`|
|warning|custom|||Input status. Mutually exclusive with `valid` and `error`|
|onBlur|function|||Called with signature `(object, event)`|
|onChange|function|||Called with signature `(object, event)`|
|onFocus|function|||Called with signature `(object, event)`|
|onKeyDown|function|||Called with signature `(object, event)`|

### FileInputField

#### Usage

To use `FileInputField`, you can import the component from the `@dhis2/ui` library  

```js
import { FileInputField } from '@dhis2/ui'
```

#### Props

|Name|Type|Default|Required|Description|
|---|---|---|---|---|
|accept|string|``'*'``||The `accept` attribute of the [native file input](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#accept)|
|buttonLabel|string │ function|``() => i18n.t('Upload a file')``||Text on the button|
|children|node||||
|className|string||||
|dataTest|string|``'dhis2-uiwidgets-fileinputfield'``|||
|disabled|boolean|||Disables the button|
|error|custom|||Applies 'error' styling to the validation text. Mutually exclusive with `warning` and `valid` props|
|helpText|string|||Useful guiding text for the user|
|initialFocus|boolean||||
|label|string|||A descriptive label above the button|
|large|custom|||Size of the button. Mutually exclusive with the `small` prop|
|multiple|boolean|||The `multiple` attribute of the [native file input](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#multiple)|
|name|string|||Name associated with input. Passed to event handler callbacks|
|placeholder|string │ function|``() => i18n.t('No file uploaded yet')``||Placeholder below the button|
|required|boolean|||Adds an asterisk to indicate this field is required|
|small|custom|||Size of the button. Mutually exclusive with the `large` prop|
|tabIndex|string||||
|valid|custom|||Applies 'valid' styling to the validation text. Mutually exclusive with `warning` and `error` props|
|validationText|string|||Text below the button that provides validation feedback|
|warning|custom|||Applies 'warning' styling to the validation text. Mutually exclusive with `valid` and `error` props|
|onBlur|function||||
|onChange|function|||Called with signature `({ name: string, files: [] }, event)`|
|onFocus|function|||Called with signature `({ name: string, files: [] }, event)`|
|onKeyDown|function|||Called with signature `({ name: string, files: [] }, event)`|

### FileInputFieldWithList

#### Usage

To use `FileInputFieldWithList`, you can import the component from the `@dhis2/ui` library  

```js
import { FileInputFieldWithList } from '@dhis2/ui'
```

#### Props

|Name|Type|Default|Required|Description|
|---|---|---|---|---|
|onChange|function||*|Called with signature `({ name: string, files: [File] }, event)`|
|accept|string|``'*'``||The `accept` attribute of the [native file input](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#accept)|
|buttonLabel|string │ function|``() => i18n.t('Upload a file')``||Text on the button|
|className|string||||
|dataTest|string|``'dhis2-uiwidgets-fileinputfield'``|||
|disabled|boolean|||Disables the button|
|error|custom|||Applies 'error' styling to the button and validation text. Mutually exclusive with `warning` and `valid` props|
|files|`arrayOf(instanceOf(File))`||||
|helpText|string|||Useful guiding text for the user|
|initialFocus|boolean||||
|label|string|||A descriptive label above the button|
|large|custom|||Size of the button. Mutually exclusive with the `small` prop|
|multiple|boolean|||The `multiple` attribute of the [native file input](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#multiple)|
|name|string|||Name associated with input. Passed to event handler callbacks|
|placeholder|string │ function|``() => i18n.t('No file uploaded yet')``||Placeholder below the button|
|removeText|string │ function|``() => i18n.t('Remove')``||Text used for the button that removes a file from the list|
|required|boolean|||Adds an asterisk to indicate this field is required|
|small|custom|||Size of the button. Mutually exclusive with the `large` prop|
|tabIndex|string||||
|valid|custom|||Applies 'valid' styling to the button and validation text. Mutually exclusive with `warning` and `error` props|
|validationText|string|||Text below the button that provides validation feedback|
|warning|custom|||Applies 'warning' styling to the button and validation text. Mutually exclusive with `valid` and `error` props|
|onBlur|function|||Called with signature `({ name: string, files: [] }, event)`|
|onFocus|function|||Called with signature `({ name: string, files: [] }, event)`|
|onKeyDown|function|||Called with signature `({ name: string, files: [] }, event)`|

### FileListItem

#### Usage

To use `FileListItem`, you can import the component from the `@dhis2/ui` library  

```js
import { FileListItem } from '@dhis2/ui'
```

#### Props

|Name|Type|Default|Required|Description|
|---|---|---|---|---|
|onRemove|function||*||
|cancelText|string||||
|className|string||||
|dataTest|string|``'dhis2-uicore-filelistitem'``|||
|label|string||||
|loading|boolean||||
|removeText|string||||
|onCancel|function||||

### FileListPlaceholder

#### Usage

To use `FileListPlaceholder`, you can import the component from the `@dhis2/ui` library  

```js
import { FileListPlaceholder } from '@dhis2/ui'
```

#### Props

|Name|Type|Default|Required|Description|
|---|---|---|---|---|
|children|string||||
|dataTest|string|``'dhis2-uicore-filelistplaceholder'``|||

### FileList

#### Usage

To use `FileList`, you can import the component from the `@dhis2/ui` library  

```js
import { FileList } from '@dhis2/ui'
```

#### Props

|Name|Type|Default|Required|Description|
|---|---|---|---|---|
|children|node||||
|className|string||||
|dataTest|string|``'dhis2-uicore-filelist'``|||