# useS3Upload API

The `useS3Upload` hook returns items needed to coordinate the upload.

```jsx
const Component = () => {
  let {
    FileInput,
    openFileDialog,
    uploadToS3,
    files,
    resetFiles
  } = useS3Upload();

  // ...
};
```

| Return value       | Description                                                                                                                      |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `FileInput`        | A component that renders a hidden file input. It needs to be rendered on the page in order to coordinate file access.            |
| `openFileDialog()` | A function that opens the browser's select a file dialog. Once a file is selected the `FileInput`'s `onChange` action will fire. |
| `uploadToS3(file)` | A function that will upload a file from a file input to your S3 bucket. For details on options, see uploadToS3 options below.    |
| `files`            | Any array of files objects, see `Files` below.                                                                                   |
| `resetFiles()`     | A function that will remove all files from the `files` array.                                                                    |

The `usePresignedUpload()` hook has the same signature as `useS3Upload` hook. You can learn more about [presigned uploads here](/presigned-uploads).

## uploadToS3 Options

The `uploadToS3` can take options that allow you to customize the request send to your API route.

```js
uploadToS3(file, {
  endpoint: {
    request: {
      url: "/api/next-s3-upload",
      body: {},
      headers: {}
    }
  }
});
```

| Option                     | Description                                                                      |
| -------------------------- | -------------------------------------------------------------------------------- |
| `endpoint.request.url`     | The location of the Next S3 Upload API route. Defaults to `/api/next-s3-upload`. |
| `endpoint.request.body`    | Additional data sent in the body payload.                                        |
| `endpoint.request.headers` | Additional HTTP request headers.                                                 |

## Files

The `files` array returned from `useS3Upload()` contains a list of files that are currently uploading or have already been uploaded. Each object in the list has the following structure.

| Key        | Description                                                                                               |
| ---------- | --------------------------------------------------------------------------------------------------------- |
| `file`     | The JavaScript [File Object](https://developer.mozilla.org/en-US/docs/Web/API/File) of the uploaded file. |
| `uploaded` | An integer representing the total number of bytes that been uploaded so far.                              |
| `size`     | An integer representing the total size of the file.                                                       |
| `progress` | The percentage (between 0 and 100) of the file that has been uploaded.                                    |
| `id`       | A unique identifier for the file.                                                                         |
