@paprika/uploader

Description

The Uploader component lets you upload files and see progress.

Installation

yarn add @paprika/uploader

or with npm:

npm install @paprika/uploader

Props

Uploader

Prop	Type	required	default	Description
a11yText	string	false	null	Accessible message for the input[type="file"].
supportedMimeTypes	arrayOf	false	["/"]	An array of accepted file extensions and/or MIME types. Note that Microsoft MIME types don't seem to be enforced.
canChooseMultiple	bool	false	true	When false the uploader only accept one file per upload.
children	node	true	-	children nodes
isDisabled	bool	false	false	Is uploader disabled.
endpoint	string	true	-	The url that will be use to upload the files.
hasAutoUpload	bool	false	true	On true will upload the file as soon they are selected or dropped
isBodyDroppable	bool	false	true	When true the user will be able to drop files at any part of the document.body. On false will only receive files dropped exactly on the FileInput area.
maxFileSize	number	false	oneMebibyte * 10	Size in Mebibytes which is used for comparing each file that will be uploaded.
onChange	func	false	() => {}	This callback fires every time the input value has been changed.
onCompleted	func	false	() => {}	Will fire once all files have been processed with the files as parameter.
headers	arrayOf	false	[]	you can pass an array of header objects.
onProcessed	func	false	() => {}	This callback fires when uploading is about to start (all files have been processed to see if they are valid type/size).
onRequest	func	false	null	Let you to take over the request method
onError	func	false	null	Callback fired whenever an error occurs while uploading a file. It receives the raw server error as an argument. Whatever this function returns is what is displayed in the UI. If nothing is returned, it will display the raw server error.
onCancel	func	false	() => {}	Callback fired when the user cancels an uploading file.
zIndex	number	false	1	z-index for popovers inside the uploader.

Usage

import { UploaderContext } from "@paprika/uploader/lib/Uploader"

function YourUI() {
  const {
    /*provided by context*/
    cancelFile,
    FileInput,
    files,
    isCompleted,
    isDisabled,
    isDraggingOver,
    isDragLeave,
    removeFile,
    upload,
  } = React.useContext(UploaderContext);

  return (
    <>
      <FileInput>
        <div css={yourStyle}>FILE INPUT ZONE</div>
      </FileInput>
      {files.length ? (
        <ul>
          {files.map(file => (
            <li>{file.filename}</li>
          ))}
        </ul>
      ) : null}
    </>
  );
}

function App() {
  return (
    <Uploader>
     <YourUI />
    </Uploader>;
  )
}

Note

maxFileSize

Size in Mebibytes which is used for comparing each file that will be uploaded you can make use of Uploader.convertUnitsToMebibytes() for easily converting units to Mebibyes ex. Uploader.convertUnitsToMebibytes(4) => 4194304 (close to 4MB);

headers:

You can pass an array of header objects ex.

   <Uploader headers={[{ "API-Key": "your-api-key" }, { Accept: "application/json" }, { "X-CSRF-Token": "your-token"} ]} ...>
     {({...}) => <YourUI />}
   </Uploader>

Context

import { UploaderContext } from "@paprika/uploader";

• children you can pass a component which can consume the Context provided.
• FileInput The input[type="file"] element ready to be consumed
• files A enhance list of the user selected files
• isCompleted Is true when all files have been processed
• isDisabled Describe the status of the component
• isDragLeave Will be true if a dragOver event occurred and leave the droppable area
• isDraggingOver Is True when detecting the user is dragging files over the droppable area
• removeFile removeFile(key) will remove a file from the files list, this function doesn't work while the file is on PROCESSING state.
• cancelFile cancelFile(key) stop the request cycle keep in mind that if it's on WAITINGFORSERVER state the server might save the file even if - the request has been cancel
• upload upload() give you the option to manually upload the files if the consumer decided to not use hasAutoUpload

FileInput Component

The <FileInput>{children}</FileInput> is a ready to use component which is passed down by the <Uploader /> context. This component has attached accessibility and attributes required to make it work correctly, you can pass any children to beautify their aspect, keep in mind that is already an input[type='file'] so avoid putting a <Button /> component or a <button /> element as a children, just make it look like one.

Endpoint

The Uploader provides a endpoint prop which you can use to point the url of the service you want to reach, Ex. <Uploader endpoint="https://yoururl.com/api/upload" ...

Accessibility

The Uploader automatically handle the on focus circle when using the <FileInput /> component on it.

• it should notify when start uploading the files and when finishing processing the files.

Links

• Storybook Showcase
• GitHub source code
• Create GitHub issue
• CHANGELOG