@asphalt-react/file-uploader v2.5.0

FileUploader

Overview

The FileUploader component is a tool for simplifying file uploads in React applications. It supports file selection through a traditional file picker or drag-and-drop functionality, with customizable intents and multiple variants to suit different use cases. The component offers flexible sizing, accessibility features like keyboard navigation and screen reader support. It handles file validation errors, supports multiple file uploads, and allows customization of labels and qualifiers, making it adaptable to a wide range of file upload scenarios.

Usage

import { FileUploader } from '@asphalt-react/file-uploader'

const accept = {
  'image/png': ['.png'],
  'text/html': ['.html', '.htm']
}

const onChange = (acceptedFiles, {rejectedFiles, event}) => {}

<FileUploader drop onChange={onChange} accept={accept} multiple />

Variants & Intents

There are 2 variations of FileUploader:

1. Inline

The inline version is a simpler variant that does not support drag and drop functionality. It provides a straightforward file selection interface where users can click a button to open the native file picker dialog. This variant is ideal for use cases where drag and drop is not necessary or desired.

2. Drag and drop

The drag and drop version includes a dropzone area where users can drag and drop files for upload. This variant enhances the user experience by providing a visual cue for file upload and supports multiple file selection simultaneously.

Drag and drop variant comes with 2 different intents:

• primary
• secondary

There are multiple combinations of the action button that can be used in both variants:

1. secondary brand
2. secondary system
3. tertiary brand
4. tertiary system

Accept File Types

By providing accept prop you can make the component accept specific file types and reject the others. The value must be an object with a common MIME type as keys and an array of file extensions as values.

const accept = {
  'image/png': ['.png'],
  'text/html': ['.html', '.htm']
}

<FileUploader accept={accept} />

Accessibility

1. The component will render native input type=file in the HTML. It will be read by screen reader as an input element.

2. FileUploader works with keyboard navigation. Pressing enter when the component is on focused, will trigger opening the file explorer window.

3. aria-invalid and aria-disabled according to the invalid and disabled prop values.

4. FileUploader accepts the input form aria-* attributes.

Props

accept

The value must be an object with a common MIME type as keys and an array of file extensions as values. For example:

accept={{ 'image/*': ['.jpg', '.png'], 'video/*': ['.mp4'] }}

brand

Applies brand styling.

system

Applies system styling.

secondary

Applies secondary styling.

tertiary

Applies tertiary styling.

caption

Caption text for the file uploader action button.

description

Description text for the file uploader.

title

Title text for the file uploader.

disabled

Disable the file uploader.

drop

Enable or disable drag and drop functionality.

invalid

Marks the file uploader as invalid.

maxFiles

Maximum number of files that can be selected.

maxSize

Maximum file size in bytes. In case of multiple files, the size is checked for each file.

minSize

Minimum file size in bytes. In case of multiple files, the size is checked for each file.

multiple

Allow multiple file selection.

onChange

Callback function when file(s) are selected. It returns these values:

• acceptedFiles: FileList
• options - an options bucket with the following properties
  • rejectedFiles: Array
    • file: File
    • errors: Array
      • code: string
      • message: string
  • event: DragEvent

function onChange(acceptedFiles, { rejectedFiles, event }) {}

qualifier

Displays an image on top of the dropzone area. By default, an image qualifier is displayed. Use false to hide the default qualifier. Provide an SVG or icon to render a custom qualifier.

actionQualifier

Add SVG or icon qualifier for action button.

size

Controls size of FileUploader. Possible values are "xs", "s", "m", "l".

showFileName

Show the file name after selection.

surfacePrimary

Applies primary surface styling.

surfaceSecondary

Applies secondary surface styling.