Skip to main content

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

NameTypeDefaultRequiredDescription
acceptstring'*'The accept attribute of the native file input
buttonLabelstring
classNamestring
dataTeststring'dhis2-uicore-fileinput'
disabledboolean
errorcustomInput status. Mutually exclusive with warning and valid
initialFocusboolean
largecustomButton size. Mutually exclusive with small
multiplebooleanThe multiple attribute of the native file input
namestring
smallcustomButton size. Mutually exclusive with large
tabIndexstring
validcustomInput status. Mutually exclusive with warning and error
warningcustomInput status. Mutually exclusive with valid and error
onBlurfunctionCalled with signature (object, event)
onChangefunctionCalled with signature (object, event)
onFocusfunctionCalled with signature (object, event)
onKeyDownfunctionCalled 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

NameTypeDefaultRequiredDescription
acceptstring'*'The accept attribute of the native file input
buttonLabelstring │ function() => i18n.t('Upload a file')Text on the button
childrennode
classNamestring
dataTeststring'dhis2-uiwidgets-fileinputfield'
disabledbooleanDisables the button
errorcustomApplies 'error' styling to the validation text. Mutually exclusive with warning and valid props
helpTextstringUseful guiding text for the user
initialFocusboolean
labelstringA descriptive label above the button
largecustomSize of the button. Mutually exclusive with the small prop
multiplebooleanThe multiple attribute of the native file input
namestringName associated with input. Passed to event handler callbacks
placeholderstring │ function() => i18n.t('No file uploaded yet')Placeholder below the button
requiredbooleanAdds an asterisk to indicate this field is required
smallcustomSize of the button. Mutually exclusive with the large prop
tabIndexstring
validcustomApplies 'valid' styling to the validation text. Mutually exclusive with warning and error props
validationTextstringText below the button that provides validation feedback
warningcustomApplies 'warning' styling to the validation text. Mutually exclusive with valid and error props
onBlurfunction
onChangefunctionCalled with signature ({ name: string, files: [] }, event)
onFocusfunctionCalled with signature ({ name: string, files: [] }, event)
onKeyDownfunctionCalled 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

NameTypeDefaultRequiredDescription
onChangefunction*Called with signature ({ name: string, files: [File] }, event)
acceptstring'*'The accept attribute of the native file input
buttonLabelstring │ function() => i18n.t('Upload a file')Text on the button
classNamestring
dataTeststring'dhis2-uiwidgets-fileinputfield'
disabledbooleanDisables the button
errorcustomApplies 'error' styling to the button and validation text. Mutually exclusive with warning and valid props
filesarrayOf(instanceOf(File))
helpTextstringUseful guiding text for the user
initialFocusboolean
labelstringA descriptive label above the button
largecustomSize of the button. Mutually exclusive with the small prop
multiplebooleanThe multiple attribute of the native file input
namestringName associated with input. Passed to event handler callbacks
placeholderstring │ function() => i18n.t('No file uploaded yet')Placeholder below the button
removeTextstring │ function() => i18n.t('Remove')Text used for the button that removes a file from the list
requiredbooleanAdds an asterisk to indicate this field is required
smallcustomSize of the button. Mutually exclusive with the large prop
tabIndexstring
validcustomApplies 'valid' styling to the button and validation text. Mutually exclusive with warning and error props
validationTextstringText below the button that provides validation feedback
warningcustomApplies 'warning' styling to the button and validation text. Mutually exclusive with valid and error props
onBlurfunctionCalled with signature ({ name: string, files: [] }, event)
onFocusfunctionCalled with signature ({ name: string, files: [] }, event)
onKeyDownfunctionCalled 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

NameTypeDefaultRequiredDescription
onRemovefunction*
cancelTextstring
classNamestring
dataTeststring'dhis2-uicore-filelistitem'
labelstring
loadingboolean
removeTextstring
onCancelfunction

FileListPlaceholder

Usage

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

import { FileListPlaceholder } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
childrenstring
dataTeststring'dhis2-uicore-filelistplaceholder'

FileList

Usage

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

import { FileList } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
childrennode
classNamestring
dataTeststring'dhis2-uicore-filelist'