File input

A file input is used to choose and upload files.

Demo

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

Demo

<FileInputField label="Upload birth certificate" />

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

Button

Demo

<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

Demo

<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

Demo

<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

import { FileInput } from '@dhis2/ui'

Props

Name	Type	Default	Required	Description
accept	string	'*'		The accept attribute of the native file input
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
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

import { FileInputField } from '@dhis2/ui'

Props

Name	Type	Default	Required	Description
accept	string	'*'		The accept attribute of the native file input
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
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

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
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
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

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

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

import { FileList } from '@dhis2/ui'

Props

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