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-widgetUsage
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#configuration8 // -----9 const options = {10 apiKey: "free", // Get API key: https://www.bytescale.com/get-started11 maxFileCount: 112 };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 === 019 ? "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#configuration8 // -----9 const options = {10 apiKey: "free", // Get API key: https://www.bytescale.com/get-started11
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 === 035 ? "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 behaviour for dropzones:
.open() only returns when showFinishButton = true (i.e. when the user clicks "Finish").
onUpdate must be used when showFinishButton = false.
Default value: showFinishButton = false
Result
The result of the open method is a Promise of:
[ { "accountId": "YOUR_ACCOUNT_ID", "filePath": "/uploads/image.jpg", "fileUrl": "https://upcdn.io/A623uY2/raw/uploads/image.jpg", "originalFile": { "accountId": "YOUR_ACCOUNT_ID", "filePath": "/uploads/image.jpg", "fileUrl": "https://upcdn.io/A623uY2/raw/uploads/image.jpg", "lastModified": 1615680311115, "metadata": { "myCustomField1": true, "myCustomField2": { "hello": "world" }, "anotherCustomField": 42 }, "mime": "image/jpeg", "originalFileName": "example.jpg", "size": 43182, "tags": [ "example_tag" ] } }]See: UploadWidgetResult
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 frameworkUploadWidget.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": { "crop": true, "cropRatio": 1, "cropShape": "circ", "preview": true } }, "layout": "modal", "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": { "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 via our File Processing APIs:
Building URLs
You should save filePath values to your DB instead of fileUrl values:
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 switch between file transformations at runtime (e.g. /raw/, /image/, etc.).
Install the Bytescale JavaScript SDK to use the UrlBuilder:
npm install @bytescale/sdkRaw Files
Use 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
Use 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
Use the UrlBuilder to transform images using the Image Processing API:
// import * as Bytescale from "@bytescale/sdk";
// Returns: "https://upcdn.io/1234abc/image/example.jpg?w=800&h=600"Bytescale.UrlBuilder.url({ accountId: "1234abc", 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
Use the UrlBuilder to transform videos using the Video Processing API:
// import * as Bytescale from "@bytescale/sdk";
// Returns: "https://upcdn.io/1234abc/video/example.mov?f=mp4-h264&h=1080"Bytescale.UrlBuilder.url({ accountId: "1234abc", 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
Use the UrlBuilder to transform audio using the Audio Processing API:
// import * as Bytescale from "@bytescale/sdk";
// Returns: "https://upcdn.io/1234abc/audio/example.wav?f=aac&br=192"Bytescale.UrlBuilder.url({ accountId: "1234abc", 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".
Archives
Use the UrlBuilder to extract the file document.docx from the uploaded ZIP file example.zip:
// import * as Bytescale from "@bytescale/sdk";
// Returns: "https://upcdn.io/1234abc/archive/example.zip?m=extract&artifact=/document.docx"Bytescale.UrlBuilder.url({ accountId: "1234abc", filePath: "/example.zip", options: { transformation: "archive", transformationParams: { m: "extract" }, artifact: "/document.docx" }});See the Archive Processing API for the full list of transformationParams when transformation: "archive".
API keys
With API key auth, the requester has access to the resources available to the API key:
Secret API keys (secret_***) have access to all API endpoints (see the Bytescale JavaScript SDK).
Public API keys (public_***) have access to file upload, file download, and file listing API endpoints. File overwrites, file deletes, and all other destructive operations cannot be performed using public API keys. File listing is also disabled by default (but can be changed by editing the API key's settings).
You must always use public API keys (e.g. public_***) in your client-side code.
Each API key can have its read/write access limited to a subset of files/folders via the API key's settings.
API keys are required. You must always pass an apiKey field via the configuration object.
Frameworks
The Upload Widget also provides NPM packages for several popular frameworks:
