File Dropzone

Allows the user to upload one or multiple files from their device. Uploads are initiated via drag and drop or the native OS file picker.

styleKeys: fileDropzone

UsageGuidelinesAPI

Use File Dropzone...

For uploading one or more files.
For uploading files by dragging and dropping.

Don't use File Dropzone...

To show the progress of uploading. Use File Tile instead.
When space on a page is limited. Use File Input instead.

Default

The File Dropzone component extends the functionality of File Input to include drag and drop functionality.

<FileDropzone
  note="or drag and drop here"
  dropNote="Drop your files here"
  multiFileErrorMessage="Upload only one file"
  aria-label="Dropzone"
>
  <FileInput multiple>
    <FileInputLabel iconPosition="left">
      <Icon iconType="upload" /> Upload from device
    </FileInputLabel>
  </FileInput>
</FileDropzone>

<FileDropzone
  note="or drag and drop here"
  dropNote="Drop your files here"
  multiFileErrorMessage="Upload only one file"
  aria-label="Dropzone"
>
  <FileInput multiple>
    <FileInputLabel iconPosition="left">
      <Icon iconType="upload" /> Upload from device
    </FileInputLabel>
  </FileInput>
</FileDropzone>

Inside of a Form

Since it is a form element, File Dropzone can be used inside a Standard Form along with a separate, external label and/or helper text. Helper text should display upload criteria such as accepted file formats and maximum file size.

<StandardForm>
  <FormField>
    <FormInputGroup>
      <FileDropzone
        note="or drag and drop here"
        dropNote="Drop your files here"
        multiFileErrorMessage="Upload only one file"
        aria-label="Dropzone"
      >
        <FileInput multiple>
          <FileInputLabel iconPosition="left">
            <Icon iconType="upload" /> Upload from device
          </FileInputLabel>
        </FileInput>
      </FileDropzone>
      <FormHelper>
        Accepted file formats: jpg, png, gif, bmp, doc and pdf under 10MB.
      </FormHelper>
    </FormInputGroup>
  </FormField>
</StandardForm>

<StandardForm>
  <FormField>
    <FormInputGroup>
      <FileDropzone
        note="or drag and drop here"
        dropNote="Drop your files here"
        multiFileErrorMessage="Upload only one file"
        aria-label="Dropzone"
      >
        <FileInput multiple>
          <FileInputLabel iconPosition="left">
            <Icon iconType="upload" /> Upload from device
          </FileInputLabel>
        </FileInput>
      </FileDropzone>
      <FormHelper>
        Accepted file formats: jpg, png, gif, bmp, doc and pdf under 10MB.
      </FormHelper>
    </FormInputGroup>
  </FormField>
</StandardForm>

Single File Upload

When multiple file upload is not enabled (on File Input), add the File Tile as a child of the File Dropzone which applies specific styling for single file upload. When multiple files are dropped on the dropzone and it's not enabled, then the dropzone will show an error on drag and only pass the first file to the input's onChange event.

<FileDropzone
  note="or drag and drop here"
  dropNote="Drop your files here"
  multiFileErrorMessage="Upload only one file"
  aria-label="Dropzone"
>
  <FileInput>
    <FileInputLabel iconPosition="left">
      <Icon iconType="upload" /> Upload from device
    </FileInputLabel>
  </FileInput>
  <FileTile
    fileName="my-file.png"
    fileSize="3.56 MB"
    accessibleTextForProgress="100% loaded"
    accessibleTextForSpinner="Waiting"
  >
    <FileTileThumbnail>
      <ResponsiveImage src="https://picsum.photos/600/400?q=1" />
    </FileTileThumbnail>
    <FileTileDeleteButton
      accessibleText="Delete file"
      onClick={() => {
        console.log('Clicked the delete button')
      }}
    />
  </FileTile>
</FileDropzone>

<FileDropzone
  note="or drag and drop here"
  dropNote="Drop your files here"
  multiFileErrorMessage="Upload only one file"
  aria-label="Dropzone"
>
  <FileInput>
    <FileInputLabel iconPosition="left">
      <Icon iconType="upload" /> Upload from device
    </FileInputLabel>
  </FileInput>
  <FileTile
    fileName="my-file.png"
    fileSize="3.56 MB"
    accessibleTextForProgress="100% loaded"
    accessibleTextForSpinner="Waiting"
  >
    <FileTileThumbnail>
      <ResponsiveImage src="https://picsum.photos/600/400?q=1" />
    </FileTileThumbnail>
    <FileTileDeleteButton
      accessibleText="Delete file"
      onClick={() => {
        console.log('Clicked the delete button')
      }}
    />
  </FileTile>
</FileDropzone>

Disabled

To disable the FileDropzone, add the disabled prop on the FileInput.

<StandardForm>
  <FormField>
    <FormInputGroup>
      <FileDropzone
        note="or drag and drop here"
        dropNote="Drop your files here"
        multiFileErrorMessage="Upload only one file"
        aria-label="Dropzone"
      >
        <FileInput multiple disabled>
          <FileInputLabel iconPosition="left">
            <Icon iconType="upload" /> Upload from device
          </FileInputLabel>
        </FileInput>
      </FileDropzone>
    </FormInputGroup>
  </FormField>
</StandardForm>

<StandardForm>
  <FormField>
    <FormInputGroup>
      <FileDropzone
        note="or drag and drop here"
        dropNote="Drop your files here"
        multiFileErrorMessage="Upload only one file"
        aria-label="Dropzone"
      >
        <FileInput multiple disabled>
          <FileInputLabel iconPosition="left">
            <Icon iconType="upload" /> Upload from device
          </FileInputLabel>
        </FileInput>
      </FileDropzone>
    </FormInputGroup>
  </FormField>
</StandardForm>

Validation

You may want to validate files when the user adds files to the dropzone such as accepted file types, max file size and total number of files. We recommend that you do this during the onChange event of the File Input. An example of some common file validation has been provided below, feel free to copy/paste and update as necessary.

File Input accept prop

Per the validation code snippet below, we have provided an example of sharing the same values in the File Input accept prop for the accepted file validation. Note that this method is recommended but you must only use individual mime types unless you update the validation function to handle wildcards. See a full implementation in the next section.

type FileWithError = {
  file: File
  errorMessage?: string
} & Partial<FileTileProps>

const validateFiles = (
  filesToValidate: File[],
  acceptedFiles?: HTMLInputElement['accept'],
  maxFiles?: number,
  maxFileSize?: number,
) => {
  const validatedFiles: FileWithError[] = filesToValidate.map((file, idx) => {
    // Check if there are too many files
    if (typeof maxFiles === 'number' && idx + 1 > maxFiles)
      return { file, errorMessage: 'Max files reached' }

    // Check if the file type matches the acceptedFiles
    if (acceptedFiles) {
      const acceptedFileRegex = new RegExp(
        acceptedFiles.replace(/\*/g, '.*').replace(/(, |,)/g, '|'),
      )
      if (!acceptedFileRegex.test(file.type)) {
        return { file, errorMessage: 'Invalid file type uploaded' }
      }
    }

    // Check if the file is too big
    if (typeof maxFileSize === 'number' && file.size > maxFileSize)
      return { file, errorMessage: 'File is too big' }

    // Otherwise return file as is
    return { file }
  })

  return validatedFiles
}

type FileWithError = {
  file: File
  errorMessage?: string
} & Partial<FileTileProps>

const validateFiles = (
  filesToValidate: File[],
  acceptedFiles?: HTMLInputElement['accept'],
  maxFiles?: number,
  maxFileSize?: number,
) => {
  const validatedFiles: FileWithError[] = filesToValidate.map((file, idx) => {
    // Check if there are too many files
    if (typeof maxFiles === 'number' && idx + 1 > maxFiles)
      return { file, errorMessage: 'Max files reached' }

    // Check if the file type matches the acceptedFiles
    if (acceptedFiles) {
      const acceptedFileRegex = new RegExp(
        acceptedFiles.replace(/\*/g, '.*').replace(/(, |,)/g, '|'),
      )
      if (!acceptedFileRegex.test(file.type)) {
        return { file, errorMessage: 'Invalid file type uploaded' }
      }
    }

    // Check if the file is too big
    if (typeof maxFileSize === 'number' && file.size > maxFileSize)
      return { file, errorMessage: 'File is too big' }

    // Otherwise return file as is
    return { file }
  })

  return validatedFiles
}

Full Implementation

This is an example of how you might implement the File Dropzone with File Tiles and file validation. Feel free to take this and tweak as necessary for your use case.

() => {
  const validateFiles = (
    filesToValidate,
    acceptedFiles,
    maxFiles,
    maxFileSize,
  ) => {
    const validatedFiles = filesToValidate.map((file, idx) => {
      // Check if there are too many files
      if (typeof maxFiles === 'number' && idx + 1 > maxFiles)
        return { file, errorMessage: 'Max files reached' }

      // Check if the file type matches the acceptedFiles
      if (acceptedFiles) {
        const acceptedFileRegex = new RegExp(
          acceptedFiles.replace(/\*/g, '.*').replace(/(, |,)/g, '|'),
        )
        if (!acceptedFileRegex.test(file.type)) {
          return { file, errorMessage: 'Invalid file type uploaded' }
        }
      }

      // Check if the file is too big
      if (typeof maxFileSize === 'number' && file.size > maxFileSize)
        return { file, errorMessage: 'File is too big' }

      // Otherwise return file as is
      return { file }
    })

    return validatedFiles
  }

  const fileTileOne = {
    imageUrl: 'https://picsum.photos/600/400?q=1',
    file: new File(['(⌐□_□)'], 'image-file.png', { type: 'image/png' }),
  }
  const fileTileTwo = {
    skin: 'loading',
    progressValue: 46,
    file: new File(['(⌐□_□)'], 'house.png', { type: 'image/png' }),
  }
  const fileTileThree = {
    skin: 'error',
    errorMessage: 'Failed to upload file',
    file: new File(['(⌐□_□)'], 'logo.png', { type: 'image/png' }),
  }
  const fileTileFour = {
    skin: 'queued',
    file: new File(['(⌐□_□)'], 'my-file.png', { type: 'image/png' }),
  }
  const [filesWithError, setFilesWithError] = React.useState([
    fileTileOne,
    fileTileTwo,
    fileTileThree,
    fileTileFour,
  ])

  const acceptedFiles = 'image/png, image/jpeg'
  const maxFiles = 4
  const maxFileSize = 3 * 1024 * 1024
  const onChange = e => {
    if (!e.target.files) return

    const eventFiles = Array.from(e.target.files)
    const customFiles = validateFiles(
      [...filesWithError.flatMap(file => file.file), ...eventFiles],
      acceptedFiles,
      maxFiles,
      maxFileSize,
    )
    setFilesWithError(customFiles)
  }

  const onDelete = index => {
    // onDelete should revalidate files as we have since changed the total number of files
    setFilesWithError(oldValues =>
      validateFiles(
        oldValues.filter((_, i) => i !== index).flatMap(file => file.file),
        acceptedFiles,
        maxFiles,
        maxFileSize,
      ),
    )
  }

  return (
    <StandardForm>
      <FormField>
        <FormInputGroup>
          <FileDropzone
            note="or drag and drop here"
            dropNote="Drop your files here"
            multiFileErrorMessage="Upload only one file"
            aria-label="Dropzone"
          >
            <FileInput multiple onChange={onChange}>
              <FileInputLabel iconPosition="left">
                <Icon iconType="upload" /> Upload from device
              </FileInputLabel>
            </FileInput>
          </FileDropzone>
          <FormHelper>
            Accepted file formats: jpg, png. Max file size: 3Mb. Max number of
            files: 4.
          </FormHelper>
        </FormInputGroup>
        <FlexBox gap={3} flexWrap="wrap" flexDirection="row">
          {filesWithError.map(
            ({ file, errorMessage, imageUrl, ...rest }, index) => (
              <FileTile
                key={file.name}
                layout="list"
                {...rest}
                skin={errorMessage ? 'error' : rest.skin}
                errorMessage={errorMessage}
                fileName={file.name}
                fileDescription={`${file.size} bytes`}
                accessibleTextForProgress={`${
                  rest.progressValue || 100
                }% loaded`}
                accessibleTextForSpinner="Waiting"
              >
                <FileTileThumbnail>
                  {imageUrl ? <ResponsiveImage src={imageUrl} /> : null}
                </FileTileThumbnail>
                <FileTileDeleteButton
                  accessibleText="Delete file"
                  onClick={() => {
                    onDelete(index)
                  }}
                />
              </FileTile>
            ),
          )}
        </FlexBox>
      </FormField>
    </StandardForm>
  )
}

() => {
  const validateFiles = (
    filesToValidate,
    acceptedFiles,
    maxFiles,
    maxFileSize,
  ) => {
    const validatedFiles = filesToValidate.map((file, idx) => {
      // Check if there are too many files
      if (typeof maxFiles === 'number' && idx + 1 > maxFiles)
        return { file, errorMessage: 'Max files reached' }

      // Check if the file type matches the acceptedFiles
      if (acceptedFiles) {
        const acceptedFileRegex = new RegExp(
          acceptedFiles.replace(/\*/g, '.*').replace(/(, |,)/g, '|'),
        )
        if (!acceptedFileRegex.test(file.type)) {
          return { file, errorMessage: 'Invalid file type uploaded' }
        }
      }

      // Check if the file is too big
      if (typeof maxFileSize === 'number' && file.size > maxFileSize)
        return { file, errorMessage: 'File is too big' }

      // Otherwise return file as is
      return { file }
    })

    return validatedFiles
  }

  const fileTileOne = {
    imageUrl: 'https://picsum.photos/600/400?q=1',
    file: new File(['(⌐□_□)'], 'image-file.png', { type: 'image/png' }),
  }
  const fileTileTwo = {
    skin: 'loading',
    progressValue: 46,
    file: new File(['(⌐□_□)'], 'house.png', { type: 'image/png' }),
  }
  const fileTileThree = {
    skin: 'error',
    errorMessage: 'Failed to upload file',
    file: new File(['(⌐□_□)'], 'logo.png', { type: 'image/png' }),
  }
  const fileTileFour = {
    skin: 'queued',
    file: new File(['(⌐□_□)'], 'my-file.png', { type: 'image/png' }),
  }
  const [filesWithError, setFilesWithError] = React.useState([
    fileTileOne,
    fileTileTwo,
    fileTileThree,
    fileTileFour,
  ])

  const acceptedFiles = 'image/png, image/jpeg'
  const maxFiles = 4
  const maxFileSize = 3 * 1024 * 1024
  const onChange = e => {
    if (!e.target.files) return

    const eventFiles = Array.from(e.target.files)
    const customFiles = validateFiles(
      [...filesWithError.flatMap(file => file.file), ...eventFiles],
      acceptedFiles,
      maxFiles,
      maxFileSize,
    )
    setFilesWithError(customFiles)
  }

  const onDelete = index => {
    // onDelete should revalidate files as we have since changed the total number of files
    setFilesWithError(oldValues =>
      validateFiles(
        oldValues.filter((_, i) => i !== index).flatMap(file => file.file),
        acceptedFiles,
        maxFiles,
        maxFileSize,
      ),
    )
  }

  return (
    <StandardForm>
      <FormField>
        <FormInputGroup>
          <FileDropzone
            note="or drag and drop here"
            dropNote="Drop your files here"
            multiFileErrorMessage="Upload only one file"
            aria-label="Dropzone"
          >
            <FileInput multiple onChange={onChange}>
              <FileInputLabel iconPosition="left">
                <Icon iconType="upload" /> Upload from device
              </FileInputLabel>
            </FileInput>
          </FileDropzone>
          <FormHelper>
            Accepted file formats: jpg, png. Max file size: 3Mb. Max number of
            files: 4.
          </FormHelper>
        </FormInputGroup>
        <FlexBox gap={3} flexWrap="wrap" flexDirection="row">
          {filesWithError.map(
            ({ file, errorMessage, imageUrl, ...rest }, index) => (
              <FileTile
                key={file.name}
                layout="list"
                {...rest}
                skin={errorMessage ? 'error' : rest.skin}
                errorMessage={errorMessage}
                fileName={file.name}
                fileDescription={`${file.size} bytes`}
                accessibleTextForProgress={`${
                  rest.progressValue || 100
                }% loaded`}
                accessibleTextForSpinner="Waiting"
              >
                <FileTileThumbnail>
                  {imageUrl ? <ResponsiveImage src={imageUrl} /> : null}
                </FileTileThumbnail>
                <FileTileDeleteButton
                  accessibleText="Delete file"
                  onClick={() => {
                    onDelete(index)
                  }}
                />
              </FileTile>
            ),
          )}
        </FlexBox>
      </FormField>
    </StandardForm>
  )
}

Forms

When using File Dropzone in a form, ensure it is wrapped in its own FormField and FormInputGroup. You can then utilise form components such as FormHelper to provide helper text. When File Tiles are rendered within the same FormField, the component will automatically pick up any errors passed through to File Tile to link them with the File Dropzone. Refer to the Full Implementation example in the Usage tab for more information.

Props

FileDropzone

This component is implemented using the <div /> as the root element. You can utilize the native attributes supported by <div /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.

See core props for additional props that can be applied to this component.

prop	type	required	description	default
note	`string`	true	The text for below the input button when in default state i.e. "or drag and drop here".	null
dropNote	`string`	true	The text for when a file is dragged onto the drop zone i.e. Drop your files here.	null
multiFileErrorMessage	`string`	true	The error message for when multiple files are dropped when single file upload only i.e. You can only upload one file	null