Upload Widget

Beautiful upload widget with support for: image previews, cropping, dragging, and more.

Installation

To install the Upload Widget, use this script tag:

<script src="https://js.bytescale.com/upload-widget/v4"></script>

Or install via NPM:

npm install @bytescale/upload-widget

Usage

To add file uploads to your web app, use these code snippets:

Option 1: Create an Upload Button

1<html>
2  <head>
3    <script src="https://js.bytescale.com/upload-widget/v4"></script>
4    <script>
5      // -----
6      // Configuration:
7      // https://www.bytescale.com/docs/upload-widget#configuration
8      // -----
9      const options = {
10        apiKey: "free", // Get API key: https://www.bytescale.com/get-started
11        maxFileCount: 1
12      };
13
14      // import * as Bytescale from "@bytescale/upload-widget";
15      Bytescale.UploadWidget.open(options).then(
16        files => {
17          const fileUrls = files.map(x => x.fileUrl).join("\n");
18          const success = fileUrls.length === 0
19            ? "No file selected."
20            : `File uploaded:\n\n${fileUrls}`;
21          alert(success);
22        },
23        error => {
24          alert(error);
25        }
26      );
27    </script>
28  </head>
29  <body></body>
30</html>

Option 2: Create a Dropzone Area

1<html>
2  <head>
3    <script src="https://js.bytescale.com/upload-widget/v4"></script>
4    <script>
5      // -----
6      // Configuration:
7      // https://www.bytescale.com/docs/upload-widget#configuration
8      // -----
9      const options = {
10        apiKey: "free", // Get API key: https://www.bytescale.com/get-started
11
12        maxFileCount: 10,
13
14        // Dropzone configuration:
15        layout: "inline",
16        container: "#my-container",
17
18        showFinishButton: true,
19
20        // To remove the 'finish' button:
21        // showFinishButton: false,
22        // onUpdate: ({ uploadedFiles, pendingFiles, failedFiles }) => {
23        //   const fileUrls = uploadedFiles.map(x => x.fileUrl).join("\n");
24        //   if (fileUrls.length > 0) {
25        //     alert(`File(s) uploaded:\n\n${fileUrls}`);
26        //   }
27        // }
28      };
29
30      // import * as Bytescale from "@bytescale/upload-widget";
31      Bytescale.UploadWidget.open(options).then(
32        files => {
33          const fileUrls = files.map(x => x.fileUrl).join("\n");
34          const success = fileUrls.length === 0
35            ? "No file selected."
36            : `File uploaded:\n\n${fileUrls}`;
37          alert(success);
38        },
39        error => {
40          alert(error);
41        }
42      );
43    </script>
44  </head>
45  <body>
46    <div id="my-container"
47         style="position: relative; margin: 0 auto; width: 80%; height: 350px;">
48    </div>
49  </body>
50</html>

Special behavior for dropzones:

The parent <div> must use position: relative and have both width and height set.

.open() only returns when showFinishButton = true (i.e. when the user clicks "Finish").

onUpdate must be used when showFinishButton = false.

Default value: showFinishButton = false

Configuration

Configuration is provided like so:

const options = {
  apiKey: "free", // Get API key: https://www.bytescale.com/get-started
  maxFileCount: 1
};

// Example 1: without a framework
UploadWidget.open(options);

// Example 2: with a framework wrapper like '@bytescale/upload-widget-react'
<UploadDropzone options={options} />

All fields are optional (except for apiKey):

{
  "apiKey": "public_A623uY2RvnNq1vZ80fYgGyhKN0U7",
  "editor": {
    "images": {
      "allowResizeOnMove": true,
      "crop": true,
      "cropFilePath": Function,
      "cropRatio": 1,
      "cropShape": "circ",
      "preview": true
    }
  },
  "layout": "modal",
  "locale": {
    "addAnotherFileBtn": "Add another file...",
    "addAnotherImageBtn": "Add another image...",
    "cancelBtn": "cancel",
    "cancelBtnClicked": "cancelled",
    "cancelPreviewBtn": "Cancel",
    "continueBtn": "Continue",
    "cropBtn": "Crop",
    "customValidationFailed": "Failed to validate file.",
    "doneBtn": "Done",
    "fileSizeLimitPrefix": "File size limit:",
    "finishBtn": "Finished",
    "finishBtnIcon": true,
    "imageCropNumberPrefix": "Image",
    "maxFilesReachedPrefix": "Maximum number of files:",
    "maxImagesReachedPrefix": "Maximum number of images:",
    "orDragDropFile": "...or drag and drop a file.",
    "orDragDropFileMulti": "...or drag and drop files.",
    "orDragDropImage": "...or drag and drop an image.",
    "orDragDropImageMulti": "...or drag and drop images.",
    "processingFile": "Processing file...",
    "removeBtn": "remove",
    "removeBtnClicked": "removed",
    "submitBtnError": "Error!",
    "submitBtnLoading": "Please wait...",
    "unsupportedFileType": "File type not supported.",
    "uploadFileBtn": "Upload a File",
    "uploadFileMultiBtn": "Upload Files",
    "uploadImageBtn": "Upload an Image",
    "uploadImageMultiBtn": "Upload Images",
    "xOfY": "of"
  },
  "maxFileCount": 1,
  "maxFileSizeBytes": 10485760,
  "metadata": {
    "myCustomField1": true,
    "myCustomField2": {
      "hello": "world"
    },
    "anotherCustomField": 42
  },
  "mimeTypes": [
    "image/jpeg"
  ],
  "multi": false,
  "onInit": Function,
  "onPreUpload": Function,
  "onUpdate": Function,
  "path": {
    "fileName": "image.jpg",
    "fileNameFallback": "image.jpg",
    "fileNameVariablesEnabled": true,
    "folderPath": "/uploads",
    "folderPathVariablesEnabled": true
  },
  "showFinishButton": true,
  "showRemoveButton": true,
  "styles": {
    "breakpoints": {
      "fullScreenHeight": 420,
      "fullScreenWidth": 750
    },
    "colors": {
      "active": "#528fff",
      "error": "#d23f4d",
      "primary": "#377dff",
      "shade100": "#333",
      "shade200": "#7a7a7a",
      "shade300": "#999",
      "shade400": "#a5a6a8",
      "shade500": "#d3d3d3",
      "shade600": "#dddddd",
      "shade700": "#f0f0f0",
      "shade800": "#f8f8f8",
      "shade900": "#fff"
    },
    "fontFamilies": {
      "base": "-apple-system, blinkmacsystemfont, Segoe UI, helvetica, arial, sans-serif"
    },
    "fontSizes": {
      "base": 16
    }
  },
  "tags": [
    "example_tag"
  ]
}

See: UploadWidgetConfig

You can disable image, video, and PDF previews by setting preview: false

You can disable the image cropper by setting crop: false

Transforming Files

You can transform uploaded files using Bytescale's File Processing APIs:

Image Processing API

Read the docs

Video Processing API

Read the docs

Audio Processing API

Read the docs

Antivirus API

Read the docs

Archive Processing API

Read the docs

Building URLs

After uploading a file, you should save its filePath to your DB instead of its fileUrl, and use the UrlBuilder to lazily create URLs:

filePath values are shorter.
filePath values allow you to change the domain in the future (e.g. if you move to a custom CNAME).
filePath values allow you to select different file transformations at runtime (e.g. /raw/, /image/, etc.).

Install the Bytescale JavaScript SDK to use the UrlBuilder:

npm install @bytescale/sdk

Raw Files

Using the UrlBuilder to get raw file URLs (i.e. URLs to original files):

// import * as Bytescale from "@bytescale/sdk";

// Returns: "https://upcdn.io/1234abc/raw/example.jpg"
Bytescale.UrlBuilder.url({
  accountId: "1234abc",
  filePath: "/example.jpg"
});

You can upload any file type to Bytescale. Use /raw/ when downloading files that don't need to be transformed.

Transformation Presets

Using the UrlBuilder to transform files using transformation presets:

// import * as Bytescale from "@bytescale/sdk";

// Returns: "https://upcdn.io/1234abc/thumbnail/example.jpg"
Bytescale.UrlBuilder.url({
  accountId: "1234abc",
  filePath: "/example.jpg",
  options: {
    transformation: "preset",
    transformationPreset: "thumbnail"
  }
});

Transformation presets are created in the Bytescale Dashboard.

Images

Using the UrlBuilder to transform images using the Image Processing API:

// import * as Bytescale from "@bytescale/sdk";

// Process images with:
// ↪ https://upcdn.io/abc1234/image/example.jpg?w=800&h=600
Bytescale.UrlBuilder.url({
  accountId: "abc1234",
  filePath: "/example.jpg",
  options: {
    transformation: "image",
    transformationParams: {
      "w": 800,
      "h": 600
    }
  }
});

See the Image Processing API for the full list of transformationParams when transformation: "image".

Videos

Using the UrlBuilder to transform videos using the Video Processing API:

// import * as Bytescale from "@bytescale/sdk";

// Process videos with:
// ↪ https://upcdn.io/abc1234/video/example.mov?f=mp4-h264&h=1080
Bytescale.UrlBuilder.url({
  accountId: "abc1234",
  filePath: "/example.mov",
  options: {
    transformation: "video",
    transformationParams: {
      "f": "mp4-h264",
      "h": 1080
    }
  }
});

See the Video Processing API for the full list of transformationParams when transformation: "video".

Audio

Using the UrlBuilder to transform audio using the Audio Processing API:

// import * as Bytescale from "@bytescale/sdk";

// Process audio with:
// ↪ https://upcdn.io/abc1234/audio/example.wav?f=aac&br=192
Bytescale.UrlBuilder.url({
  accountId: "abc1234",
  filePath: "/example.wav",
  options: {
    transformation: "audio",
    transformationParams: {
      "f": "aac",
      "br": 192
    }
  }
});

See the Audio Processing API for the full list of transformationParams when transformation: "audio".

Antivirus

Using the UrlBuilder to scan files for viruses, trojans, and other malware:

// import * as Bytescale from "@bytescale/sdk";

// Returns: "https://upcdn.io/1234abc/antivirus/example.zip"
Bytescale.UrlBuilder.url({
  accountId: "1234abc",
  filePath: "/example.zip",
  options: {
    transformation: "antivirus"
  }
});

See the Antivirus API for full details about the JSON response structure.

Authentication

The Bytescale Upload Widget requires a Bytescale API key, and optionally a JWT:

API keys

You must always pass an apiKey to the Upload Widget configuration object.

With API key auth, the requester has access to the resources configured in the API key's permissions.

Secret API keys: can perform all API operations (see the Bytescale JavaScript SDK).
Public API keys: can perform file uploads and file downloads only. File overwrites, file deletes, and all other destructive operations cannot be performed using public API keys.

You must always use public API keys (e.g. public_***) in your client-side code.

When using public API keys you can optionally pass a JWT to extend the requester's permissions beyond that of the API key. In addition, you can configure your API key to make it reject requests that aren't accompanied by a valid JWT. This prevents users from taking your API key and using it outside of your application.

JWTs are issued by your application and are verified by Bytescale using a public key certificate.

To use JWTs, please use the Bytescale JavaScript SDK AuthManager »

Frameworks

The Upload Widget provides NPM packages for several popular frameworks:

React

Read the docs

Angular

Read the docs

Vue

Read the docs

jQuery

Read the docs

Was this section helpful? Yes No

You are using an outdated browser.

This website requires a modern web browser -- the latest versions of these browsers are supported:

UI Widgets

SDKs

Processing APIs

Core APIs

Data Types

More Resources

Upload Widget

Installation

Usage

Option 2: Create a Dropzone Area

Result

Configuration

Transforming Files

Building URLs

Raw Files

Transformation Presets

Images

Videos

Audio

Archives

Antivirus

Authentication

API keys

JWTs (Optional)

Frameworks

Upload Widget

You are using an outdated browser.