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

File Dropzone is only available in the React API for SWAN.

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.

note and dropNoteare deprecated in SWAN 3.24. These prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system and remove these prop.

<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
        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
        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.

If multiple files are dropped onto File Dropzone and multiple file upload is not enabled, then the dropzone will show an error on drag and only pass the first file to the input's onChange event.

<FileDropzone
  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" progressValue={100}>
    <FileTileThumbnail>
      <ResponsiveImage src="/example-images/5x4.webp" />
    </FileTileThumbnail>
    <FileTileDeleteButton
      onClick={() => {
        console.log('Clicked the delete button')
      }}
    />
  </FileTile>
</FileDropzone>

<FileDropzone
  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" progressValue={100}>
    <FileTileThumbnail>
      <ResponsiveImage src="/example-images/5x4.webp" />
    </FileTileThumbnail>
    <FileTileDeleteButton
      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
        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
        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
}

File Upload pattern

File Dropzone is part of a larger pattern of uploading files. The File Upload pattern ensures users are presented with a consistent UI regardless of the file types uploaded or the specific page navigated to.

For more information, see File Upload.

<GridContainer>
  <Row>
    <Column span={12}>
      <StandardForm>
        <GridContainer>
          <Row mb="between-subsections">
            <Column span={12}>
              <FormField>
                <FormInputGroup>
                  <FileDropzone
                    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, JPEG, BMP, PNG, GIF, HEIC
                  </FormHelper>
                </FormInputGroup>
              </FormField>
            </Column>
          </Row>
          <Row verticalGap="matchGutter">
            <Column spanXs={6} spanSm={4} spanMd={4} span={3} spanXl={2}>
              <FileTile
                skin="loading"
                progressValue={40}
                fileName="my-file.png"
                fileDescription="3.56 MB"
              >
                <FileTileThumbnail>
                  <ResponsiveImage src="/example-images/1x1.webp" />
                </FileTileThumbnail>
                <FileTileDeleteButton />
              </FileTile>
            </Column>
            <Column spanXs={6} spanSm={4} spanMd={4} span={3} spanXl={2}>
              <FileTile fileName="my-file.png" fileDescription="3.56 MB">
                <FileTileThumbnail>
                  <ResponsiveImage src="/example-images/5x4.webp" />
                </FileTileThumbnail>
                <FileTileDeleteButton />
              </FileTile>
            </Column>
            <Column spanXs={6} spanSm={4} spanMd={4} span={3} spanXl={2}>
              <FileTile fileName="my-file.png" fileDescription="3.56 MB">
                <FileTileThumbnail>
                  <ResponsiveImage src="/example-images/9x16.webp" />
                </FileTileThumbnail>
                <FileTileDeleteButton />
              </FileTile>
            </Column>
            <Column spanXs={6} spanSm={4} spanMd={4} span={3} spanXl={2}>
              <FileTile fileName="my-file.png" fileDescription="3.56 MB">
                <FileTileThumbnail>
                  <ResponsiveImage src="/example-images/16x9.webp" />
                </FileTileThumbnail>
                <FileTileDeleteButton />
              </FileTile>
            </Column>
            <Column spanXs={6} spanSm={4} spanMd={4} span={3} spanXl={2}>
              <FileTile fileName="my-file.png" fileDescription="3.56 MB">
                <FileTileThumbnail>
                  <ResponsiveImage src="/example-images/1x1-2.webp" />
                </FileTileThumbnail>
                <FileTileDeleteButton />
              </FileTile>
            </Column>
            <Column spanXs={6} spanSm={4} spanMd={4} span={3} spanXl={2}>
              <FileTile fileName="my-file.png" fileDescription="3.56 MB">
                <FileTileThumbnail>
                  <ResponsiveImage src="/example-images/5x4-2.webp" />
                </FileTileThumbnail>
                <FileTileDeleteButton />
              </FileTile>
            </Column>
          </Row>
        </GridContainer>
      </StandardForm>
    </Column>
  </Row>
</GridContainer>

<GridContainer>
  <Row>
    <Column span={12}>
      <StandardForm>
        <GridContainer>
          <Row mb="between-subsections">
            <Column span={12}>
              <FormField>
                <FormInputGroup>
                  <FileDropzone
                    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, JPEG, BMP, PNG, GIF, HEIC
                  </FormHelper>
                </FormInputGroup>
              </FormField>
            </Column>
          </Row>
          <Row verticalGap="matchGutter">
            <Column spanXs={6} spanSm={4} spanMd={4} span={3} spanXl={2}>
              <FileTile
                skin="loading"
                progressValue={40}
                fileName="my-file.png"
                fileDescription="3.56 MB"
              >
                <FileTileThumbnail>
                  <ResponsiveImage src="/example-images/1x1.webp" />
                </FileTileThumbnail>
                <FileTileDeleteButton />
              </FileTile>
            </Column>
            <Column spanXs={6} spanSm={4} spanMd={4} span={3} spanXl={2}>
              <FileTile fileName="my-file.png" fileDescription="3.56 MB">
                <FileTileThumbnail>
                  <ResponsiveImage src="/example-images/5x4.webp" />
                </FileTileThumbnail>
                <FileTileDeleteButton />
              </FileTile>
            </Column>
            <Column spanXs={6} spanSm={4} spanMd={4} span={3} spanXl={2}>
              <FileTile fileName="my-file.png" fileDescription="3.56 MB">
                <FileTileThumbnail>
                  <ResponsiveImage src="/example-images/9x16.webp" />
                </FileTileThumbnail>
                <FileTileDeleteButton />
              </FileTile>
            </Column>
            <Column spanXs={6} spanSm={4} spanMd={4} span={3} spanXl={2}>
              <FileTile fileName="my-file.png" fileDescription="3.56 MB">
                <FileTileThumbnail>
                  <ResponsiveImage src="/example-images/16x9.webp" />
                </FileTileThumbnail>
                <FileTileDeleteButton />
              </FileTile>
            </Column>
            <Column spanXs={6} spanSm={4} spanMd={4} span={3} spanXl={2}>
              <FileTile fileName="my-file.png" fileDescription="3.56 MB">
                <FileTileThumbnail>
                  <ResponsiveImage src="/example-images/1x1-2.webp" />
                </FileTileThumbnail>
                <FileTileDeleteButton />
              </FileTile>
            </Column>
            <Column spanXs={6} spanSm={4} spanMd={4} span={3} spanXl={2}>
              <FileTile fileName="my-file.png" fileDescription="3.56 MB">
                <FileTileThumbnail>
                  <ResponsiveImage src="/example-images/5x4-2.webp" />
                </FileTileThumbnail>
                <FileTileDeleteButton />
              </FileTile>
            </Column>
          </Row>
        </GridContainer>
      </StandardForm>
    </Column>
  </Row>
</GridContainer>

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`	false	⚠️ Deprecated - This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support. The text for below the input button when in default state i.e. "or drag and drop here".	null
dropNote	`string`	false	⚠️ Deprecated - This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support. 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