Default parameters

BaselineWidely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2016.

Default function parameters allow named parameters to be initialized with default values if no value orundefined is passed.

Try it

function multiply(a, b = 1) {  return a * b;}console.log(multiply(5, 2));// Expected output: 10console.log(multiply(5));// Expected output: 5

Syntax

function fnName(param1 = defaultValue1, /* …, */ paramN = defaultValueN) {  // …}

Description

In JavaScript, function parameters default toundefined. However, it's often useful to set a different default value. This is where default parameters can help.

In the following example, if no value is provided forb whenmultiply is called,b's value would beundefined when evaluatinga * b andmultiply would returnNaN.

function multiply(a, b) {  return a * b;}multiply(5, 2); // 10multiply(5); // NaN !

In the past, the general strategy for setting defaults was to test parameter values in the function body and assign a value if they areundefined. In the following example,b is set to1 ifmultiply is called with only one argument:

function multiply(a, b) {  b = typeof b !== "undefined" ? b : 1;  return a * b;}multiply(5, 2); // 10multiply(5); // 5

With default parameters, checks in the function body are no longer necessary. Now, you can assign1 as the default value forb in the function head:

function multiply(a, b = 1) {  return a * b;}multiply(5, 2); // 10multiply(5); // 5multiply(5, undefined); // 5

Parameters are still set left-to-right, overwriting default parameters even if there are later parameters without defaults.

function f(x = 1, y) {  return [x, y];}f(); // [1, undefined]f(2); // [2, undefined]

Note:The first default parameter and all parameters after it will not contribute to the function'slength.

The default parameter initializers live in their own scope, which is a parent of the scope created for the function body.

This means that earlier parameters can be referred to in the initializers of later parameters. However, functions and variables declared in the function body cannot be referred to from default value parameter initializers; attempting to do so throws a run-timeReferenceError. This also includesvar-declared variables in the function body.

For example, the following function will throw aReferenceError when invoked, because the default parameter value does not have access to the child scope of the function body:

function f(a = go()) {  function go() {    return ":P";  }}f(); // ReferenceError: go is not defined

This function will print the value of theparametera, because the variablevar a is hoisted only to the top of the scope created for the function body, not the parent scope created for the parameter list, so its value is not visible tob.

function f(a, b = () => console.log(a)) {  var a = 1;  b();}f(); // undefinedf(5); // 5

The default parameter allows any expression, but you cannot useawait oryield that would pause the evaluation of the default expression. The parameter must be initializedsynchronously.

async function f(a = await Promise.resolve(1)) {  return a;}

Note:Because the default parameter is evaluated when the function is called, not when the function is defined, the validity of theawait andyield operators depends on the function itself, not its surrounding function. For example, if the current function is notasync,await will be parsed as an identifier and follow normalidentifier syntax rules, even when this function is nested in anasync function.

Examples

Passing undefined vs. other falsy values

In the second call in this example, even if the first argument is set explicitly toundefined (though notnull or otherfalsy values), the value of thenum argument is still the default.

function test(num = 1) {  console.log(typeof num);}test(); // 'number' (num is set to 1)test(undefined); // 'number' (num is set to 1 too)// test with other falsy values:test(""); // 'string' (num is set to '')test(null); // 'object' (num is set to null)

Evaluated at call time

The default argument is evaluated atcall time. Unlike with Python (for example), a new object is created each time the function is called.

function append(value, array = []) {  array.push(value);  return array;}append(1); // [1]append(2); // [2], not [1, 2]

This even applies to functions and variables:

function callSomething(thing = something()) {  return thing;}let numberOfTimesCalled = 0;function something() {  numberOfTimesCalled += 1;  return numberOfTimesCalled;}callSomething(); // 1callSomething(); // 2

Earlier parameters are available to later default parameters

Parameters defined earlier (to the left) are available to later default parameters:

function greet(name, greeting, message = `${greeting} ${name}`) {  return [name, greeting, message];}greet("David", "Hi"); // ["David", "Hi", "Hi David"]greet("David", "Hi", "Happy Birthday!"); // ["David", "Hi", "Happy Birthday!"]

This functionality can be approximated like this, which demonstrates how many edge cases are handled:

function go() {  return ":P";}function withDefaults(  a,  b = 5,  c = b,  d = go(),  e = this,  f = arguments,  g = this.value,) {  return [a, b, c, d, e, f, g];}function withoutDefaults(a, b, c, d, e, f, g) {  switch (arguments.length) {    case 0:    case 1:      b = 5;    case 2:      c = b;    case 3:      d = go();    case 4:      e = this;    case 5:      f = arguments;    case 6:      g = this.value;  }  return [a, b, c, d, e, f, g];}withDefaults.call({ value: "=^_^=" });// [undefined, 5, 5, ":P", {value:"=^_^="}, arguments, "=^_^="]withoutDefaults.call({ value: "=^_^=" });// [undefined, 5, 5, ":P", {value:"=^_^="}, arguments, "=^_^="]

Destructured parameter with default value assignment

You can use default value assignment with thedestructuring syntax.

A common way of doing that is to set an empty object/array as the default value for the destructured parameter; for example:[x = 1, y = 2] = []. This makes it possible to pass nothing to the function and still have those values prefilled:

function preFilledArray([x = 1, y = 2] = []) {  return x + y;}preFilledArray(); // 3preFilledArray([]); // 3preFilledArray([2]); // 4preFilledArray([2, 3]); // 5// Works the same for objects:function preFilledObject({ z = 3 } = {}) {  return z;}preFilledObject(); // 3preFilledObject({}); // 3preFilledObject({ z: 2 }); // 2