Skip to Content
Patternfly Logo

File upload

Info alert:Beta feature

This Beta component is currently under review, so please join in and give us your feedback on the PatternFly forum
ExamplesPropsCSS Variables

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 onChange props. The type prop determines how the FileUpload component behaves upon accepting a file, what type of value it passes to its onChange prop, and what type it expects for its value prop.

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 onChange prop as a string (along with its filename). Typing/pasting text in the box will also call onChange with a string, and a string value is expected for the value prop.

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:

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 to onChange 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 properties
NameTypeRequiredDefaultDescription
idstringYesUnique id for the TextArea, also used to generate ids for accessible labels.
type'text' | 'dataURL'NoWhat type of file. Determines what is is passed to `onChange` and expected by `value` (a string for 'text' and 'dataURL', or a File object otherwise.
valuestring | FileNotype === fileReaderType.text || type === fileReaderType.dataURL ? '' : nullValue of the file's contents (string if text file, File object otherwise)
filenamestringNo''Value to be shown in the read-only filename field.
onChange( value: string | File, filename: string, event: | React.DragEvent<HTMLElement> // User dragged/dropped a file | React.ChangeEvent<HTMLTextAreaElement> // User typed in the TextArea | React.MouseEvent<HTMLButtonElement, MouseEvent> // User clicked Clear button ) => voidNo() => {}A callback for when the file contents change.
classNamestringNoAdditional classes added to the FileUpload container element.
isDisabledbooleanNoFlag to show if the field is disabled.
isReadOnlybooleanNoFlag to show if the field is read only.
isLoadingbooleanNoFlag to show if a file is being loaded.
spinnerAriaValueTextstringNoAria-valuetext for the loading spinner
isRequiredbooleanNoFlag to show if the field is required.
validated'success' | 'error' | 'default'No
aria-labelstringNoAria-label for the TextArea.
filenamePlaceholderstringNoPlaceholder string to display in the empty filename field
filenameAriaLabelstringNoAria-label for the read-only filename field
browseButtonTextstringNoText for the Browse button
clearButtonTextstringNoText for the Clear button
hideDefaultPreviewbooleanNoFlag to hide the built-in preview of the file (where available). If true, you can use children to render an alternate preview.
allowEditingUploadedTextbooleanNoFlag to allow editing of a text file's contents after it is selected from disk
childrenReact.ReactNodeNonullAdditional children to render after (or instead of) the file preview.
onReadStarted(fileHandle: File) => voidNo() => {}A callback for when a selected file starts loading
onReadFinished(fileHandle: File) => voidNo() => {}A callback for when a selected file finishes loading
onReadFailed(error: DOMException, fileHandle: File) => voidNo() => {}A callback for when the FileReader API fails
dropzonePropsDropzonePropsNo{}Optional extra props to customize react-dropzone.
FileUploadField properties
NameTypeRequiredDefaultDescription
idstringYesUnique id for the TextArea, also used to generate ids for accessible labels
type'text' | 'dataURL'NoWhat type of file. Determines what is is expected by `value` (a string for 'text' and 'dataURL', or a File object otherwise).
valuestring | FileNo''Value of the file's contents (string if text file, File object otherwise)
filenamestringNo''Value to be shown in the read-only filename field.
onChange( value: string, filename: string, event: | React.ChangeEvent<HTMLTextAreaElement> // User typed in the TextArea | React.MouseEvent<HTMLButtonElement, MouseEvent> // User clicked Clear button ) => voidNo() => {}A callback for when the TextArea value changes.
classNamestringNo''Additional classes added to the FileUploadField container element.
isDisabledbooleanNofalseFlag to show if the field is disabled.
isReadOnlybooleanNofalseFlag to show if the field is read only.
isLoadingbooleanNofalseFlag to show if a file is being loaded.
spinnerAriaValueTextstringNoAria-valuetext for the loading spinner
isRequiredbooleanNofalseFlag to show if the field is required.
validated'success' | 'error' | 'default'No'default'
aria-labelstringNo'File upload'Aria-label for the TextArea.
filenamePlaceholderstringNo'Drag a file here or browse to upload'Placeholder string to display in the empty filename field
filenameAriaLabelstringNofilename ? 'Read only filename' : filenamePlaceholderAria-label for the read-only filename field
browseButtonTextstringNo'Browse...'Text for the Browse button
clearButtonTextstringNo'Clear'Text for the Clear button
isClearButtonDisabledbooleanNo!filename && !valueFlag to disable the Clear button
hideDefaultPreviewbooleanNofalseFlag to hide the built-in preview of the file (where available). If true, you can use children to render an alternate preview.
allowEditingUploadedTextbooleanNofalseFlag to allow editing of a text file's contents after it is selected from disk
childrenReact.ReactNodeNonullAdditional children to render after (or instead of) the file preview.
onBrowseButtonClick(event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => voidNo() => {}A callback for when the Browse button is clicked.
onClearButtonClick(event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => voidNo() => {}A callback for when the Clear button is clicked.
isDragActivebooleanNofalseFlag to show if a file is being dragged over the field
containerRefReact.Ref<HTMLDivElement>NonullA reference object to attach to the FileUploadField container element.

CSS Variables

--pf-c-file-upload__file-details__c-form-control--MinHeightc_file_upload__file_details__c_form_control_MinHeight
calc(4rem*2)
--pf-c-file-upload__file-select__c-button--m-control--disabled--after--BorderBottomColorc_file_upload__file_select__c_button_m_control_disabled_after_BorderBottomColor
#8a8d90
--pf-c-file-upload__file-select__c-button--m-control--disabled--after--BorderLeftColorc_file_upload__file_select__c_button_m_control_disabled_after_BorderLeftColor
#ededed
--pf-c-file-upload__file-select__c-button--m-control--disabled--after--BorderRightColorc_file_upload__file_select__c_button_m_control_disabled_after_BorderRightColor
#ededed
--pf-c-file-upload__file-select__c-button--m-control--disabled--after--BorderTopColorc_file_upload__file_select__c_button_m_control_disabled_after_BorderTopColor
#ededed
--pf-c-file-upload__file-select__c-button--m-control--disabled--after--BorderWidthc_file_upload__file_select__c_button_m_control_disabled_after_BorderWidth
1px
--pf-c-file-upload__file-select__c-button--m-control--disabled--BackgroundColorc_file_upload__file_select__c_button_m_control_disabled_BackgroundColor
#ededed
--pf-c-file-upload__file-select__c-button--m-control--OutlineOffsetc_file_upload__file_select__c_button_m_control_OutlineOffset
calc(-1*0.25rem)
--pf-c-file-upload--m-drag-hover--after--BackgroundColorc_file_upload_m_drag_hover_after_BackgroundColor
#06c
--pf-c-file-upload--m-drag-hover--after--Opacityc_file_upload_m_drag_hover_after_Opacity
.1
--pf-c-file-upload--m-drag-hover--before--BorderColorc_file_upload_m_drag_hover_before_BorderColor
#06c
--pf-c-file-upload--m-drag-hover--before--BorderWidthc_file_upload_m_drag_hover_before_BorderWidth
1px
--pf-c-file-upload--m-drag-hover--before--ZIndexc_file_upload_m_drag_hover_before_ZIndex
100
--pf-c-file-upload--m-loading__file-details--before--BackgroundColorc_file_upload_m_loading__file_details_before_BackgroundColor
#fff
--pf-c-file-upload--m-loading__file-details--before--Bottomc_file_upload_m_loading__file_details_before_Bottom
1px
--pf-c-file-upload--m-loading__file-details--before--Leftc_file_upload_m_loading__file_details_before_Left
1px
--pf-c-file-upload--m-loading__file-details--before--Rightc_file_upload_m_loading__file_details_before_Right
1px