Introduced in JavaScript 1.8.5

Summary

Creates a new function that, when called, itself calls this function in the context of the provided this value, with a given sequence of arguments preceding any provided when the new function was called.

Syntax

fun.bind(thisArg[, arg1[, arg2[, ...]]])

Parameters

thisArg

The value to be passed as the this parameter to the target function when the bound function is called.  The value is ignored if the bound function is constructed using the new operator.

arg1, arg2, ...

Arguments to prepend to arguments provided to the bound function when invoking the target function.

Description

The bind function creates a new function (a bound function) with the same function body (internal Call attribute in ECMAScript 5 terms) as the function it is being called on (the bound function's target function) with the this value bound to the first argument of bind, which cannot be overridden. bind also accepts leading default arguments to provide to the target function when the bound function is called.  A bound function may also be constructed using the new operator: doing so acts as though the target function had instead been constructed.  The provided this value is ignored, while prepended arguments are provided to the emulated function.

Compatibility

The bind function is a recent addition to ECMA-262, 5th edition; as such it may not be present in all browsers. You can partially work around this by inserting the following code at the beginning of your scripts, allowing use of much of the functionality of bind in implementations that do not natively support it.

if (!Function.prototype.bind) {
  Function.prototype.bind = function (oThis) {
    if (typeof this !== "function") {
      // closest thing possible to the ECMAScript 5 internal IsCallable function
      throw new TypeError("Function.prototype.bind - what is trying to be bound is not callable");
    }

    var fSlice = Array.prototype.slice,
        aArgs = fSlice.call(arguments, 1), 
        fToBind = this, 
        fNOP = function () {},
        fBound = function () {
          return fToBind.apply(this instanceof fNOP
                                 ? this
                                 : oThis || window,
                               aArgs.concat(fSlice.call(arguments)));
        };

    fNOP.prototype = this.prototype;
    fBound.prototype = new fNOP();

    return fBound;
  };
}

Some of the many differences (there may well be others, as this list does not seriously attempt to be exhaustive) between this algorithm and the specified algorithm are:

• The partial implementation relies Array.prototype.slice, Array.prototype.concat, Function.prototype.call and Function.prototype.apply, built-in methods to have their original values.
• The partial implementation creates functions that do not have immutable "poison pill" caller and arguments properties that throw a TypeError upon get, set, or deletion. (This could be added if the implementation supports Object.defineProperty, or partially implemented [without throw-on-delete behavior] if the implementation supports the __defineGetter__ and __defineSetter__ extensions.)
• The partial implementation creates functions that have a prototype property. (Proper bound functions have none.)
• The partial implementation creates bound functions whose length property does not agree with that mandated by ECMA-262: it creates functions with length 0, while a full implementation, depending on the length of the target function and the number of pre-specified arguments, may return a non-zero length.

If you choose to use this partial implementation, you must not rely on those cases where behavior deviates from ECMA-262, 5th edition! With some care, however (and perhaps with additional modification to suit specific needs), this partial implementation may be a reasonable bridge to the time when bind is widely implemented according to the specification.

Examples

var x = 9; 
var module = {
  x: 81,
  getX: function() { return this.x; }
};

module.getX(); // 81

var getX = module.getX;
getX(); // 9, because in this case, "this" refers to the global object

// create a new function with 'this' bound to module
var boundGetX = getX.bind(module);
boundGetX(); // 81

function list() {
  return Array.prototype.slice.call(arguments);
}

var list1 = list(1, 2, 3); // [1, 2, 3]

//  Create a function with a preset leading argument
var leadingZeroList = list.bind(undefined, 37);

var list2 = leadingZeroList(); // [37]
var list3 = leadingZeroList(1, 2, 3); // [37, 1, 2, 3]

function Point(x, y) {
  this.x = x;
  this.y = y;
}

Point.prototype.toString = function() { 
  return this.x + "," + this.y; 
};

var p = new Point(1, 2);
p.toString(); // "1,2"


var emptyObj = {};
var YAxisPoint = Point.bind(emptyObj, 0 /* x */);

var axisPoint = new YAxisPoint(5);
axisPoint.toString(); //  "0,5"

axisPoint instanceof Point; // true
axisPoint instanceof YAxisPoint; // true
new Point(17, 42) instanceof YAxisPoint; // false with native bind // true, when using the above polyfill

// Example can be run directly in your JavaScript console
// ...continuing from above

// Can still be called as a normal function (although usually this is undesired)
YAxisPoint(13);

emptyObj.x + "," + emptyObj.y;
// >  "0,13"

var slice = Array.prototype.slice;

// ...

slice.call(arguments);

var slice = Function.prototype.call.bind(Array.prototype.slice);

// ...

slice(arguments);

Supplemental

One interesting wrinkle of bound functions working "as expected" with the new operator is that it is now possible to implement what one might call "Function.prototype.construct", an analog to Function.prototype.apply that takes an array of values as its sole argument, constructing this function with the provided arguments using the new operator:

// Function.prototype.construct will work with the Function.prototype.bind defined above

if (!Function.prototype.construct) { 
  Function.prototype.construct = function(aArgs) {

    if (aArgs.constructor !== Array)
      throw new TypeError("second argument to Function.prototype.construct must be an array");

    var aBoundArgs = Array.prototype.concat.apply([null], aArgs), 
        fBound = this.bind.apply(this, aBoundArgs);
        
    return new fBound();

  };
}

// Now consider the string "2011-7-16 19:35:46". Without an analog of the Function.apply method for constructors,
// you would run a lot of steps in order to construct a Date object from it:

var aDateArgs = "2011-7-16 19:35:46".split(/[- :]/),
    oMyDate1 = new Date(aDateArgs[0], aDateArgs[1], aDateArgs[2], aDateArgs[3], aDateArgs[4], aDateArgs[5]);
alert(oMyDate1.toLocaleString());


// With the Function.construct method we could do the same thing with a single step:
var oMyDate2 = Date.construct("2011-7-16 19:35:46".split(/[- :]/));
alert(oMyDate2.toLocaleString());

// Here is another example:

function Point(x, y) {
  this.x = x;
  this.y = y;
}

Point.prototype.toString = function() { 
  return this.x + "," + this.y; 
};

alert(Point.construct([2, 4]).toString()); // "2,4"

But note well: the efficiency of constructing a new function every time you wish to construct an object by invoking a bound function via new with a variable number of arguments is questionable. Your code will be faster and more efficient if you use Function.prototype.apply instead, with normal call syntax rather than using new operator-based syntax.

Browser compatibility

Based on Kangax's compat tables

See also

• Function.prototype.apply
• Function.prototype.call