JS: Function Argument Destructure

By Xah Lee. Date: . Last updated: .

New in ES2015.

Function Argument Destructure is a convenient syntax that lets you easily:

For example, you have a function draw_circle that takes a object:

draw_circle({center:[3,4], radius:5})

You want to have parameters x, y as center, and r as radius.

Normally, you write it like this:

function draw_circle (obj) {
    let x = obj.center[0];
    let y = obj.center[1];
    let r = obj.radius;

    return [x,y,r];

}

console.log (
    draw_circle({center:[3,4], radius:5})
); // [ 3, 4, 5 ]

With Function Argument Destructure, you can write it like this:

function draw_circle ({center:[x,y], radius:r}) {
    return [ x, y, r ];
}

console.log (
    draw_circle ({center:[3,4], radius:5})
);
// [ 3, 4, 5 ]

Destructure works with arrow function too.

[see JS: Arrow Function]

Array to Variables

Array Destructure Summary
Definition in parameter explanation
([x,y]) Sample call f([3,4]). x gets 3, y gets 4.
([x=9, y=10]) with default for each slot. (if arg has less items)
([x,y] = [8,9]) with default for whole array
([x=1,y=2] = [1,2]) with default for each slot or whole array

Here's simple destructuring of array.

// f take 1 array arg. First slot is assigned to var x, and second is y

const f = (([x,y]) => x+y);

console.log ( f([3,4]) === 7); // true

Here's destructure of array with default values for each slot.

// h take 1 array arg. First slot is assigned to var x, and second is y. If the arg has length less than 2, they get default values
function h ( [ x=9, y=10]) { console.log ( x, y ); }

h([3,4]); // 3 4
h([3]); // 3 10

// h()
// TypeError: Cannot match against 'undefined' or 'null'.

Here's destructure of array with default value for the whole array.

// h2 take 1 array arg. first slot is assigned to var x, and second is y. If no arg, default to [8,9]
function h2 ([x,y] = [8,9]) { console.log ( x, y ); }
h2(); // 8 9
h2([3]); // 3 undefined
h2([3,4]); // 3 4

Here's destructure of array with default values for each slot and the whole array.

// h3 take 1 array arg. first slot is assigned to var x, and second is y. If the arg is not given, or If array length less than 2, they get default values 1, 2

function h3 ([x=1,y=2] = [1,2]) { console.log ( x, y ); }
h3(); // 1 2
h3([9]); // 9 2
h3([9,8]); // 9 8

Object to Variables

Object Destructure Summary
Definition in parameter explanation
({a:x, b:y})Sample call f(obj). Gets values of keys a b and assign them to var x y.
({a:x=9, b:y}) use default for missing keys.
({a,b})get values of keys a b, use the same names as variables.
({x=1, y=2}) use default for missing keys.
({x=1, y=2}={x:1, y:2}) also use default for whole object if it's not given.

Here's simple destructuring of object.

// g take 1 object arg, and it should have keys a and b. The value of these keys are assigned to vars x and y as param names
function g ({a:x, b:y}) { console.log ( x, y ); }
g({b:3, a:4}); // 4 3

You don't have to get all keys in argument.

// g take 1 object arg, and the key name joe and mary are significant. Their values will be used as parameters, named x and y
function g ({joe:x, mary:y}) { console.log ( x, y ); }
g( {john:3, mary:4, joe:7, cat:6 }); // 7 4

Destructure Object with Default Values for Keys

Give default values for missing keys.

// g take 1 object arg, and it should have keys a and b. The value of these keys are assigned to vars x and y as param names. If key “a” is missing, default to 9
function g ({a:x=9, b:y}) { console.log ( x, y ); }
g({b:3, c:4}); // 9 3

Give default values for missing keys, and also a default object if no argument is passed at all.

// g take 1 object arg, and it should have keys a and b. The value of these keys are assigned to vars x and y as param names. key a b defaults to 1 2
function g ({a:x=1, b:y=2} = {a:1, b:2}) { console.log ( x, y ); }
g(); // 1 2
g({b:3}); // 1 3
g({b:3, c:4}); // 1 3
g({b:8, a:9}); // 9 8

Use Key Names as Variable Names

If you want the variable names to have the same names as property keys, there's a syntax shortcut.

// g take 1 object arg, and it should have keys a and b. The value of these keys are assigned to vars a b
function g ({a,b}) { console.log ( a, b ); }
g({b:3, a:4}); // 4 3

Now with default values for missing keys:

// g take 1 object arg, and it should have keys x and y. The value defaults to 1 2

function g ({x=1, y=2} ) { console.log ( x, y ); }

g({y:3}); // 1 3
g({y:3, c:4}); // 1 3
g({y:8, x:9}); // 9 8

With default values for missing keys, and also provide default if no argument is given:

// g take 1 object arg, and it should have keys x and y. The value defaults to 1 2
function g ({x=1, y =2} = {x:1, y:2}) { console.log ( x, y ); }
g(); // 1 2
g({y:3}); // 1 3
g({y:3, c:4}); // 1 3
g({y:8, x:9}); // 9 8

Here's more complex destructuring example, with 2 object arguments.

// destructuring example, with 2 object arguments

// g takes 2 args, each is a object.
function g ({a,b}, {c=1, d=1} = {c:1,d:1}) { return [a, b, c, d]; }

// give all params
console.log(
    g({b:3,a:4}, {c:5,d:6})
); // [ 4, 3, 5, 6 ]

// omit second param, default is {c:1,d:1}
console.log(
    g({b:3,a:4})
); // [ 4, 3, 1, 1 ]

// omit parts of second param. each has default of 1
console.log(
    g({b:3,a:4}, {d:9})
); // [ 4, 3, 1, 9 ]

See also: JS: Destructuring Assignment

JS Function

  1. Define Function
  2. Arrow Function ⭐
  3. Function Params
  4. “arguments” Object
  5. Rest Params ⭐
  6. Arg Default Value ⭐
  7. Arg Destructure ⭐
  8. f Declaration vs Expression
  9. Closure
  10. f call apply bind
  11. Functional Programing

Like it? Help me by telling your friends. Or, Put $5 at patreon.

Or, Buy JavaScript in Depth

If you have a question, put $5 at patreon and message me.

Web Dev Tutorials

  1. HTML
  2. CSS
  3. JavaScript
  4. JS Obj Ref
  5. DOM
  6. SVG
  7. Blog