Data Types


The configuration object passed to the Upload Widget's open() method has this structure:



"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": [
"multi": false,
"onInit": Function,
"onUpdate": Function,
"onValidate": 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": [



The container element to render the widget in.

Supported values:

string: a DOM selector for an existing element on the page, e.g. "body" or "#container".

object: a DOM element.

Only add this property if layout is set to "inline".

Required: No


Image editor options for the Upload Widget.

Type: UploadWidgetEditor

Required: No


If "modal" is used, then the Upload Widget will render as a modal when open() is called.

If "inline" is used, then the Upload Widget will render as an inline dropzone when open() is called.

If "inline" is used, then you must set the container property to point to the element you want to render the dropzone widget inside.

Default: "modal"

Type: String

Allowed Values: "inline", "modal"

Required: No


Text to appear in the Upload Widget's buttons and other UI elements. Defaults to the EN/US locale.

Type: UploadWidgetLocale

Required: No


Maximum number of files allowed.

Default: infinity if multi=true

Type: Number

Required: No


Maximum file size allowed.

Default: infinity

Type: Number

Required: No


Arbitrary JSON to store against the uploaded file(s) as metadata.

You can retrieve this later via a GetFileDetails request.

Type: FileMetadata

Required: No


File type filter.

Example: ["image/jpeg"]

Type: String[]

Required: No


Enables/disables multiple file uploads.

Default: false

Type: Boolean

Required: No


Callback taking a parameter of type UploadWidgetMethods.

Fired once when the widget is first displayed.

Type: Function

Required: No


Callback taking an array of type UploadWidgetResult.

Fired each time a file is uploaded or removed.

Type: Function

Required: No


Callback taking a DOM File object.

Fired before each file upload.

If Promise<string> is returned, then the string is displayed to the user as a validation error message and the upload is cancelled.

If Promise<undefined> is returned, then the upload is allowed to continue.

Type: Function

Required: No


The path to upload the file(s) to.

Type: FilePathDefinition

Required: No


Shows/hides the 'finish' button, which is displayed after files are uploaded.

If showFinishButton = false, multi = false, and layout = "modal", then the modal will close immediately after the file is uploaded (instead of showing the file to the user).

Default: true

Type: Boolean

Required: No


Shows/hides the 'remove' button, which is displayed next to each file after it's uploaded.

Default: true

Type: Boolean

Required: No


Styling options for the Upload Widget.

Type: UploadWidgetStyles

Required: No


The tags you specify here determine which rules will be executed for the upload(s).

You create rules in the Upload Dashboard, and choose which tags trigger each rule.

Rules include: max file size checks, traffic limit checks, rate limit checks, etc.

Example: ["example_tag"]

Type: String[]

Required: No

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: