Skip to content
PatternFly logo

File upload

A file upload component allows the users to upload a single file into the browser.

Examples

The basic FileUpload component can accept a file via browse or drag-and-drop, and behaves like a standard form field with its value and onFileInputChange event that is similar to <input onChange="..."> prop. The type prop determines how the FileUpload component behaves upon accepting a file, what type of value it passes to its onDataChange event.

Text files

If type="text" is passed (and hideDefaultPreview is not), a TextArea preview will be rendered underneath the filename bar. When a file is selected, its contents will be read into memory and passed to the onDataChange event as a string. Every filename change is passed to onFileInputChange same as it would do with the <input> element. Pressing Clear button triggers onClearClick event.

Simple text file

A user can always type instead of selecting a file, but by default, once a user selects a text file from their disk they are not allowed to edit it (to prevent unintended changes to a format-sensitive file). This behavior can be changed with the allowEditingUploadedText prop. Typing/pasting text in the box will call onTextChange with a string, and a string value is expected for the value prop. :

Text file with edits allowed

Restricting file size and type

Any props accepted by react-dropzone's Dropzone component can be passed as a dropzoneProps object in order to customize the behavior of the Dropzone, such as restricting the size and type of files allowed. The following example will only accept CSV files smaller than 1 KB. Note that file type determination is not reliable across platforms (see the note on react-dropzone's docs about the accept prop), so be sure to test the behavior of your file upload restriction on all browsers and operating systems targeted by your application.

IMPORTANT: A note about security

Restricting file sizes and types in this way is for user convenience only, and it cannot prevent a malicious user from submitting anything to your server. As with any user input, your application should also validate, sanitize and/or reject restricted files on the server side.

Text file with restrictions

Upload a CSV file

Other file types

If no type prop is specified, the component will not read files directly. When a file is selected, a File object will be passed as a second argument to onFileInputChange and your application will be responsible for reading from it (e.g. by using the FileReader API or attaching it to a FormData object). A File object will also be expected for the value prop instead of a string, and no preview of the file contents will be shown by default. The onReadStarted and onReadFinished callbacks will also not be called since the component is not reading the file.

Simple file of any format

Customizing the file preview

Regardless of type, the preview area (the TextArea, or any future implementations of default previews for other types) can be removed by passing hideDefaultPreview, and a custom one can be rendered by passing children.

Custom file preview

Bringing your own file browse logic

FileUpload is a thin wrapper around the FileUploadField presentational component. If you need to implement your own logic for accepting files, you can instead render a FileUploadField directly, which does not include react-dropzone and requires additional props (e.g. onBrowseButtonClick, onClearButtonClick, isDragActive).

Note that the isLoading prop is styled to position the spinner dead center above the entire component, so it should not be used with hideDefaultPreview unless a custom empty-state preview is provided via children. The below example prevents isLoading and hideDefaultPreview from being used at the same time. You can always provide your own spinner as part of the children!

Custom file upload


Props

FileUpload

The main file upload component with drag and drop functionality built in by default.
*required
NameTypeDefaultDescription
idrequiredstringUnique id for the text area. Also used to generate ids for accessible labels.
allowEditingUploadedTextbooleanFlag to allow editing of a text file's contents after it is selected from disk.
aria-labelstringAria-label for the text area.
browseButtonTextstringText for the browse button.
childrenReact.ReactNodenullAdditional children to render after (or instead of) the file preview.
classNamestringAdditional classes added to the file upload container element.
clearButtonTextstringText for the clear button.
dropzonePropsPartial<DropzoneProps>{}Optional extra props to customize react-dropzone.
filenamestring''Value to be shown in the read-only filename field.
filenameAriaLabelstringAria-label for the read-only filename field.
filenamePlaceholderstringPlaceholder string to display in the empty filename field.
hideDefaultPreviewbooleanFlag to hide the built-in preview of the file (where available). If true, you can use the children property to render an alternate preview.
isDisabledbooleanFlag to show if the field is disabled.
isLoadingbooleanFlag to show if a file is being loaded.
isReadOnlybooleanFlag to show if the field is read only.
isRequiredbooleanFlag to show if the field is required.
Deprecated: onChange( value: string | File, filename: string, event: | React.MouseEvent<HTMLButtonElement, MouseEvent> // Clear button was clicked | React.DragEvent<HTMLElement> // User dragged/dropped a file | React.ChangeEvent<HTMLElement> // User typed in the TextArea ) => void() => {}A callback for when the file contents changes. Please instead use onFileInputChange, onTextChange, onDataChange, and onClearClick individually.
onClearClickReact.MouseEventHandler<HTMLButtonElement>Clear button was clicked.
onClick(event: React.MouseEvent) => voidevent => event.preventDefault()Callback for clicking on the file upload field text area. By default, prevents a click in the text area from opening file dialog.
onDataChange(data: string) => voidOn data changed - if type='text' or type='dataURL' and file was loaded it will call this method
onFileInputChange(event: React.ChangeEvent<HTMLInputElement> | React.DragEvent<HTMLElement>, file: File) => voidnullChange event emitted from the hidden \<input type="file" \> field associated with the component
onReadFailed(error: DOMException, fileHandle: File) => void() => {}A callback for when the FileReader API fails.
onReadFinished(fileHandle: File) => void() => {}A callback for when a selected file finishes loading.
onReadStarted(fileHandle: File) => void() => {}A callback for when a selected file starts loading.
onTextChange(text: string) => voidText area text changed.
spinnerAriaValueTextstringAria-valuetext for the loading spinner.
type'text' | 'dataURL'What type of file. Determines what is passed to the onChange property and what is expected by the value property (a string for 'text' and 'dataURL', or a File object otherwise.
validated'success' | 'error' | 'default'Value to indicate if the field is modified to show that validation state. If set to success, field will be modified to indicate valid state. If set to error, field will be modified to indicate error state.
valuestring | Filetype === fileReaderType.text || type === fileReaderType.dataURL ? '' : nullValue of the file's contents (string if text file, File object otherwise).

FileUploadField

A more customizable file upload component for implementing custom logic. Drag and drop functionality is not built in by default.
*required
NameTypeDefaultDescription
idrequiredstringUnique id for the text area. Also used to generate ids for accessible labels.
allowEditingUploadedTextbooleanfalseFlag to allow editing of a text file's contents after it is selected from disk.
aria-labelstring'File upload'Aria-label for the text area.
browseButtonTextstring'Browse...'Text for the browse button.
childrenReact.ReactNodenullAdditional children to render after (or instead of) the file preview.
classNamestring''Additional classes added to the file upload field container element.
clearButtonTextstring'Clear'Text for the clear button.
containerRefReact.Ref<HTMLDivElement>nullA reference object to attach to the file upload field container element.
filenamestring''Value to be shown in the read-only filename field.
filenameAriaLabelstringfilename ? 'Read only filename' : filenamePlaceholderAria-label for the read-only filename field.
filenamePlaceholderstring'Drag a file here or browse to upload'Placeholder string to display in the empty filename field.
hideDefaultPreviewbooleanfalseFlag to hide the built-in preview of the file (where available). If true, you can use the children property to render an alternate preview.
isClearButtonDisabledboolean!filename && !valueFlag to disable the clear button.
isDisabledbooleanfalseFlag to show if the field is disabled.
isDragActivebooleanfalseFlag to show if a file is being dragged over the file upload field.
isLoadingbooleanfalseFlag to show if a file is being loaded.
isReadOnlybooleanfalseFlag to show if the field is read only.
isRequiredbooleanfalseFlag to show if the field is required.
onBrowseButtonClick(event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void() => {}A callback for when the browse button is clicked.
onChange( value: string, filename: string, event: | React.ChangeEvent<HTMLTextAreaElement> // User typed in the TextArea | React.MouseEvent<HTMLButtonElement, MouseEvent> // User clicked Clear button ) => void() => {}A callback for when the text area value changes.
onClearButtonClick(event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void() => {}A callback for when the clear button is clicked.
onTextAreaBlur(event?: any) => voidCallback for when focus is lost on the text area field.
onTextAreaClick(event: React.MouseEvent<HTMLTextAreaElement, MouseEvent>) => voidA callback for when the text area is clicked. Can also be set via the onClick property of the file upload component.
onTextChange(text: string) => voidText area text changed.
spinnerAriaValueTextstringAria-valuetext for the loading spinner.
textAreaPlaceholderstring''Placeholder string to display in the empty text area field.
type'text' | 'dataURL'What type of file. Determines what is is expected by the value property (a string for 'text' and 'dataURL', or a File object otherwise).
validated'success' | 'error' | 'default''default'Value to indicate if the field is modified to show that validation state. If set to success, field will be modified to indicate valid state. If set to error, field will be modified to indicate error state.
valuestring | File''Value of the file's contents (string if text file, File object otherwise).

CSS variables

.pf-c-file-upload--pf-c-file-upload--m-loading__file-details--before--BackgroundColor
#fff
.pf-c-file-upload--pf-c-file-upload--m-loading__file-details--before--Left
1px
.pf-c-file-upload--pf-c-file-upload--m-loading__file-details--before--Right
1px
.pf-c-file-upload--pf-c-file-upload--m-loading__file-details--before--Bottom
1px
.pf-c-file-upload--pf-c-file-upload--m-drag-hover--before--BorderWidth
1px
.pf-c-file-upload--pf-c-file-upload--m-drag-hover--before--BorderColor
#06c
.pf-c-file-upload--pf-c-file-upload--m-drag-hover--before--ZIndex
100
.pf-c-file-upload--pf-c-file-upload--m-drag-hover--after--BackgroundColor
#06c
.pf-c-file-upload--pf-c-file-upload--m-drag-hover--after--Opacity
.1
.pf-c-file-upload--pf-c-file-upload__file-details__c-form-control--MinHeight
calc(4rem * 2)
.pf-c-file-upload--pf-c-file-upload__file-select__c-button--m-control--OutlineOffset
calc(-1 * 0.25rem)

View source on GitHub