@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