@asphalt-react/file-uploader

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:

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

• 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:

• secondary brand
• secondary system
• tertiary brand
• 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

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

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

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

• 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'] }}

type	required	default
objectOf	false	{}

brand

Applies brand styling.

type	required	default
bool	false	false

system

Applies system styling.

type	required	default
bool	false	false

secondary

Applies secondary styling.

type	required	default
bool	false	false

tertiary

Applies tertiary styling.

type	required	default
bool	false	false

caption

Caption text for the file uploader action button.

type	required	default
string	false	"Browse File"

description

Description text for the file uploader.

type	required	default
string	false	"Choose file to upload"

title

Title text for the file uploader.

type	required	default
string	false	"Upload Files"

disabled

Disable the file uploader.

type	required	default
bool	false	false

drop

Enable or disable drag and drop functionality.

type	required	default
bool	false	false

invalid

Marks the file uploader as invalid.

type	required	default
bool	false	false

maxFiles

Maximum number of files that can be selected.

type	required	default
number	false	0

maxSize

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

type	required	default
number	false	N/A

minSize

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

type	required	default
number	false	0

multiple

Allow multiple file selection.

type	required	default
bool	false	false

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 }) {}

type	required	default
func	false	N/A

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.

type	required	default
union	false	true

actionQualifier

Add SVG or icon qualifier for action button.

type	required	default
element	false	null

size

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

type	required	default
enum	false	"m"

showFileName

Show the file name after selection.

type	required	default
bool	false	true

surfacePrimary

Applies primary surface styling.

type	required	default
bool	false	false

surfaceSecondary

Applies secondary surface styling.

type	required	default
bool	false	false