@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