Image upload 2.0.0 - Documentation

The image configuration must be set.

image: {
  insertByUpload: true,
  uploadURL: "/images",
  uploadParams: { param1: "abc123" }


The insertByUpload configuration specifies whether image uploads are enabled. By default, this is set to false. To enable image uploads, it must be set to true.

Upload URL

The uploadURL configuration specifies the URL to upload images to.

uploadURL: "/images"

Upload Parameters (optional)

The uploadParams configuration specifies any custom parameters to pass to the server when uploading images. The default is {}.

uploadParams: { param1: "abc123" }


Depending on browser support, multiple images may be uploaded at one time. If the browser supports it, each image is resized to fit within the width of SnapEditor. Depending on browser support, the upload will either be via XHR or IFrame transport.

The POST contains the following data.

file: The actual file. This also contains the filename.
max_width: The width of the editor in case the server wants to do its own resizing.
param1: Custom param 1 using the uploadParams configuration.
param2: Custom param 2 using the uploadParams configuration.


SnapEditor concentrates on creating the best online HTML5 WYSIWYG text editor, hence we do not provide a server-side implementation of the upload API for every single language. That said, we will try our best to help out.

On the server-side, the POST must be handled at the URL specified by the uploadURL configuration.

These are the general steps to handle the POST request.

  1. Ensure the request is a POST and contains at least file data. If not, return an error response.
  2. Ensure the filename is valid. We suggest the regular expression of /^[^\/]+[.](gif|jpg|jpeg|png)$/i. If not, return an error response.
  3. Ensure the file is not too large. If not, return an error response.
  4. Save the image.
  5. Generate the public URL where the image can be accessed from the browser.
  6. Return a success response with the public URL and the correct Content-Type.

Responses should be a JSON object with the following format.

  "status_code": 200,
  "message": "Success",
  "url": "" // url not required on error

Internet Explorer 8 and 9

Internet Explorer 8 and 9 treat the JSON response as a file to download.

On a server, a JSON response should have a Content-Type of application/json. This is fine if the request was via XHR. However, Internet Explorer 8 and 9 uses IFrame transport. This is what causes the download.

To fix this problem, the Content-Type of the server response must be tweaked if the request was not via XHR.

If the request is not via XHR, simply set the Content-Type to text/plain or text/html instead of application/json.

Error Codes

Here is a list of status codes and possible messages to return. The exact message returned is up to you.

  • 200 - "Success"
  • 400 - "Bad Request"
  • 403 - "Invalid Filename"
  • 405 - "File Too Large"

Ruby Gem

For those that use Ruby, we have written a Rack middleware which handles simple server-side uploading and is distributed as a gem under the name "snapimage". It also comes with a pre-built image server. For more information, visit the SnapImage homepage. We hope to support more languages in the future.

Browser Support

Multiple Uploads

  • Firefox
  • Chrome
  • Safari (desktop)
  • Microsoft Internet 10+

Single Upload

  • Microsoft Internet 8
  • Microsoft Internet 9

Client-side Resize

  • Firefox
  • Chrome
  • Safari (desktop)
  • Microsoft Internet 10+


  • Firefox
  • Chrome
  • Safari (desktop)
  • Microsoft Internet 10+

IFrame Transport

  • Microsoft Internet 8
  • Microsoft Internet 9