Info alert:Beta feature
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.
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:
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.
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.
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
.
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
!
Props
FileUpload
Name | Type | Required | Default | Description |
---|---|---|---|---|
allowEditingUploadedText | boolean | No | Flag to allow editing of a text file's contents after it is selected from disk | |
aria-label | string | No | Aria-label for the TextArea. | |
browseButtonText | string | No | Text for the Browse button | |
children | React.ReactNode | No | null | Additional children to render after (or instead of) the file preview. |
className | string | No | Additional classes added to the FileUpload container element. | |
clearButtonText | string | No | Text for the Clear button | |
dropzoneProps | DropzoneProps | No | {} | Optional extra props to customize react-dropzone. |
filename | string | No | '' | Value to be shown in the read-only filename field. |
filenameAriaLabel | string | No | Aria-label for the read-only filename field | |
filenamePlaceholder | string | No | Placeholder string to display in the empty filename field | |
hideDefaultPreview | boolean | No | Flag to hide the built-in preview of the file (where available). If true, you can use children to render an alternate preview. | |
id | string | Yes | Unique id for the TextArea, also used to generate ids for accessible labels. | |
isDisabled | boolean | No | Flag to show if the field is disabled. | |
isLoading | boolean | No | Flag to show if a file is being loaded. | |
isReadOnly | boolean | No | Flag to show if the field is read only. | |
isRequired | boolean | No | Flag to show if the field is required. | |
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 ) => void | No | () => {} | A callback for when the file contents change. |
onReadFailed | (error: DOMException, fileHandle: File) => void | No | () => {} | A callback for when the FileReader API fails |
onReadFinished | (fileHandle: File) => void | No | () => {} | A callback for when a selected file finishes loading |
onReadStarted | (fileHandle: File) => void | No | () => {} | A callback for when a selected file starts loading |
spinnerAriaValueText | string | No | Aria-valuetext for the loading spinner | |
type | 'text' | 'dataURL' | No | What 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. | |
validated | 'success' | 'error' | 'default' | No | 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. | |
value | string | File | No | type === fileReaderType.text || type === fileReaderType.dataURL ? '' : null | Value of the file's contents (string if text file, File object otherwise) |
FileUploadField
Name | Type | Required | Default | Description |
---|---|---|---|---|
allowEditingUploadedText | boolean | No | false | Flag to allow editing of a text file's contents after it is selected from disk |
aria-label | string | No | 'File upload' | Aria-label for the TextArea. |
browseButtonText | string | No | 'Browse...' | Text for the Browse button |
children | React.ReactNode | No | null | Additional children to render after (or instead of) the file preview. |
className | string | No | '' | Additional classes added to the FileUploadField container element. |
clearButtonText | string | No | 'Clear' | Text for the Clear button |
containerRef | React.Ref<HTMLDivElement> | No | null | A reference object to attach to the FileUploadField container element. |
filename | string | No | '' | Value to be shown in the read-only filename field. |
filenameAriaLabel | string | No | filename ? 'Read only filename' : filenamePlaceholder | Aria-label for the read-only filename field |
filenamePlaceholder | string | No | 'Drag a file here or browse to upload' | Placeholder string to display in the empty filename field |
hideDefaultPreview | boolean | No | false | Flag to hide the built-in preview of the file (where available). If true, you can use children to render an alternate preview. |
id | string | Yes | Unique id for the TextArea, also used to generate ids for accessible labels | |
isClearButtonDisabled | boolean | No | !filename && !value | Flag to disable the Clear button |
isDisabled | boolean | No | false | Flag to show if the field is disabled. |
isDragActive | boolean | No | false | Flag to show if a file is being dragged over the field |
isLoading | boolean | No | false | Flag to show if a file is being loaded. |
isReadOnly | boolean | No | false | Flag to show if the field is read only. |
isRequired | boolean | No | false | Flag to show if the field is required. |
onBrowseButtonClick | (event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void | No | () => {} | 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 | No | () => {} | A callback for when the TextArea value changes. |
onClearButtonClick | (event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void | No | () => {} | A callback for when the Clear button is clicked. |
spinnerAriaValueText | string | No | Aria-valuetext for the loading spinner | |
type | 'text' | 'dataURL' | No | What type of file. Determines what is is expected by `value` (a string for 'text' and 'dataURL', or a File object otherwise). | |
validated | 'success' | 'error' | 'default' | No | '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. |
value | string | File | No | '' | 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