npm package: @paprika/uploader
Description: The Uploader component lets you upload files and see progress.
Author: @paprika
Latest version: 7.0.4

<!-- start: Autogenerated - do not modify -->

# @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.                                                                                                                                                                                                     |

<!-- end: Autogenerated - do not modify -->
<!-- content -->

## Usage

```js
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.

```js
   <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.

<!-- eoContent -->

## Links

- [Storybook Showcase](https://paprika.highbond.com/?path=/story/forms-uploader--showcase)
- [GitHub source code](https://github.com/acl-services/paprika/tree/master/packages/Uploader/src)
- [Create GitHub issue](https://github.com/acl-services/paprika/issues/new?label=[]&title=@paprika/uploader%20[help]:%20your%20short%20description&body=%0A%23%20Help%20wanted%0A%0A%23%23%20Please%20write%20your%20question.%0A*A%20clear%20and%20concise%20description%20of%20what%20the%20question%20is*%0A%0A%23%23%20Additional%20context%0A*Add%20any%20other%20context%20or%20screenshots%20about%20your%20question%20here.*%0A)
- [CHANGELOG](https://github.com/acl-services/paprika/tree/master/packages/Uploader/CHANGELOG.md)