Better abstraction for XMLHttpRequest

bower install better-xhr


Build Status Coverage Status Bower version

Better abstraction for XMLHttpRequest

The goal for the project is to create simple to use, lightweight and Promise-based implementation for working with AJAX.


XHR.get("/test/url").then(function(response) {
    // do something with response
});"/test/modify/url", {data: {a: "b"}}).then(successCallback, errorCallback);

// or general method
XHR(method, url, config).then(success, fail);

Global XHR function returns a Promise object. Check out the article HTML5Rocks article for details on it's API.


Use bower to download the library with all required dependencies.

bower install better-xhr

This will clone the latest version of the better-xhr into the bower_components directory at the root of your project.

Then just append the following scripts on your page:

<script src="bower_components/better-xhr/dist/better-xhr.js"></script>

NOTE: for browsers that don't have a Promise yet, include a polyfill.


You can modify XMLHttpRequest settings via properties of the config object.

Property Type Description
data Object or String Specifies data that you want to send in AJAX request.

An object value is serialized via query string algorithm.

For GET requests data argument is appended directly to the request URL.

For non-GET requests it will be passed into the XMLHttpRequest#send call.

Adds "Content-Type" header with value "application/x-www-form-urlencoded" for non-GET requests
json Object or String Specifies JSON data for AJAX request.

An object value is serialized via JSON.stringify.

Adds "Content-Type" header with value "application/json"
headers Object Specifies extra HTTP headers for request. You can drop any default header via setting it to null
cacheBurst String Cache bursting parameter. Allows to specify name of the extra dummy argument that disables caching.

Default value: "_"
timeout Number The argument specifies request timeout in miliseconds.

Default value: 15000
charset String Specifies character encoding.

Default value: "UTF-8"
emulateHTTP String Truthy value specifies name of the extra URL parameter to emulate additional HTTP methods for older servers. Also triggers setting of the X-HTTP-Method-Override header to the appropriate value before sending an AJAX request.
mimeType String Used to specify returned data type and to override value of the Content-Type header which is used by default to understand how to parse response.

Has several shortcuts: json, text.

Method serialize

The plugin introduces static method XHR.serialize. This method can be used to collect a form data for AJAX requests. Returned object is a key/value map of form elements. For example

<form id="myform" action="/some-url">
    <input type="text" name="user" value="user1">
    <select name="gender">
        <option value="m" selected>Male</option>
        <option value="f">Female</option>

can be serialized like below:

// => {user: "user1", "gender": "m"}


XHR.defaults object contains all predefined default values. You can modify them on demand. For example:

// set default timeout to 10 seconds
XHR.defaults.timeout = 10000; 
// add custom header for each request
XHR.defaults.headers["Authorization"] = "Basic Zm9vOmJhcg==";

Browser support


  • Chrome
  • Safari 6.0+
  • Firefox 16+
  • Internet Explorer 8+
  • Opera 12.10+


  • iOS Safari 6+
  • Android 2.3+
  • Chrome for Android

NOTE: for IE8-9 cross-domain requests are not supported because of limited capabilities of legacy XDomainRequest object.