Configures the uploading of local images to your application using's built in upload mechanism.

This property can be configured to either:

  • Upload Images using a form POST
  • Upload Images via a Custom JavaScript Upload Handler Function


To use's built-in upload mechanism, use upload.url, upload.basePath, and upload.credentials.

urlString Defines the location of your POST acceptor script. This is the URL to which images will be uploaded.
basePathString [Optional] Defines the base path of images uploaded in your application. This path is combined with the path returned from your POST acceptor script.
credentialsBooleanfalse[Optional] true: sends cookies with the upload POST (sets the XHR credentials flag). false: does not send cookies.

To use a custom JavaScript handler function, use upload.handler. Note that defining upload.handler disables's built in upload mechanism.

handlerFunction Configures the uploading of images to your application using a custom Javascript upload handler.



Using's Built-in Upload Mechanism

The simplest way to handle images is use automatic background uploads. A simple configuration object is used to define the upload location for images. basePath is used in conjunction with the value returned by the POST handler to link to the uploaded image within the editor's content. More information is available in the Handling Local Images guide.


var config = {
	images : {
		upload : {
			url : '',
            basePath : ''

var editor = textboxio.replace('#targetId', config);


Using a Custom JavaScript Upload Handling Function

If images must be uploaded using more than a simple HTTP POST, the entire upload process can be replaced. For example, you may wish to perform additional client side validation or manipulation on the images prior to their upload.  The handler function is passed three arguments; Data (object), Success (function) and Failure (function).

Data Object Properties

The first argument is an object providing information about the image that has been inserted. All properties are functions.

Property FunctionTypeDescription



JavaScript Blob instance representing the image binary data

data.base64() String

A copy of the image binary data pre-converted to base64 for your convenience

data.filename()StringThe actual filename, where possible, otherwise a generated filename based on the MIME type unique identifier for this image
Success Function Parameters

 The second argument is a function that indicates the upload has successfully completed



The URL to use as the image src. No post-processing is performed on this value (the basePath configuration property is ignored).

Failure Function Parameters

The third argument is a function that indicates the upload failed.


String (optional)

A message to display to the user in an error banner.

This value is optional - if you do not wish to translate your error a generic message is available which has been translated into all supported languages.

var config = {
	images : {
		upload : {
			handler : function (data, success, failure) {
				// For example, if myuploader.upload() returns a promise, e.g. jQuery ajax
				myuploader.upload(data.blob(), data.filename()).then(function (<upload response>) {
					success(<response image url>);
				}, function () {
					failure("my failure message");
var editor = textboxio.replace('#targetId', config);