The destructuring assignment syntax is a JavaScript expression that makes it possible to extract data from arrays or objects into distinct variables.
Syntax
var a, b, rest;
[a, b] = [1, 2];
console.log(a); // 1
console.log(b); // 2
[a, b, ...rest] = [1, 2, 3, 4, 5];
console.log(a); // 1
console.log(b); // 2
console.log(rest); // [3, 4, 5]
({a, b} = {a:1, b:2});
console.log(a); // 1
console.log(b); // 2
({a, b, ...rest} = {a:1, b:2, c:3, d:4});
// ES7 - not implemented in Firefox 47a01
Description
The object and array literal expressions provide an easy way to create ad hoc packages of data.
var x = [1, 2, 3, 4, 5];
The destructuring assignment uses similar syntax, but on the left-hand side of the assignment to define what elements to extract from the sourced variable.
var x = [1, 2, 3, 4, 5]; var [y, z] = x; console.log(y); // 1 console.log(z); // 2
This capability is similar to features present in languages such as Perl and Python.
Array destructuring
Basic variable assignment
var foo = ["one", "two", "three"]; var [one, two, three] = foo; console.log(one); // "one" console.log(two); // "two" console.log(three); // "three"
Assignment separate from declaration
A variable can be assigned its value via destructuring separate from the variable's declaration.
var a, b; [a, b] = [1, 2]; console.log(a); // 1 console.log(b); // 2
Default values
A variable can be assigned a default, in the case that the value pulled from the array is undefined.
var a, b; [a=5, b=7] = [1]; console.log(a); // 1 console.log(b); // 7
Swapping variables
Two variables values can be swapped in one destructuring expression.
Without destructuring assignment, swapping two values requires a temporary variable (or, in some low-level languages, the XOR-swap trick).
var a = 1; var b = 3; [a, b] = [b, a]; console.log(a); // 3 console.log(b); // 1
Parsing an array returned from a function
It's always been possible to return an array from a function. Destructuring can make working with an array return value more concise.
In this example, f() returns the values [1, 2] as its output, which can be parsed in a single line with destructuring.
function f() {
return [1, 2];
}
var a, b;
[a, b] = f();
console.log(a); // 1
console.log(b); // 2
Ignoring some returned values
You can ignore return values that you're not interested in:
function f() {
return [1, 2, 3];
}
var [a, , b] = f();
console.log(a); // 1
console.log(b); // 3
You can also ignore all returned values:
[,,] = f();
Pulling values from a regular expression match
When the regular expression exec() method finds a match, it returns an array containing first the entire matched portion of the string and then the portions of the string that matched each parenthesized group in the regular expression. Destructuring assignment allows you to pull the parts out of this array easily, ignoring the full match if it is not needed.
var url = "https://developer.mozilla.org/en-US/Web/JavaScript"; var parsedURL = /^(\w+)\:\/\/([^\/]+)\/(.*)$/.exec(url); console.log(parsedURL); // ["https://developer.mozilla.org/en-US/Web/JavaScript", "https", "developer.mozilla.org", "en-US/Web/JavaScript"] var [, protocol, fullhost, fullpath] = parsedURL; console.log(protocol); // "https"
Object destructuring
Basic assignment
var o = {p: 42, q: true};
var {p, q} = o;
console.log(p); // 42
console.log(q); // true
Assignment without declaration
A variable can be assigned its value with destructuring separate from its declaration.
var a, b;
({a, b} = {a:1, b:2});
The ( .. ) around the assignment statement is required syntax when using object literal destructuring assignment without a declaration.
{a, b} = {a:1, b:2} is not valid stand-alone syntax, as the {a, b} on the left-hand side is considered a block and not an object literal.
However, ({a, b} = {a:1, b:2}) is valid, as is var {a, b} = {a:1, b:2}
Assigning to new variable names
A variable can be extracted from an object and assigned to a variable with a different name than the object property.
var o = {p: 42, q: true};
var {p: foo, q: bar} = o;
console.log(foo); // 42
console.log(bar); // true
Default values
A variable can be assigned a default, in the case that the value pulled from the object is undefined.
var {a=10, b=5} = {a: 3};
console.log(a); // 3
console.log(b); // 5
Setting a function parameter's default value
ES5 version
function drawES5Chart(options) {
options = options === undefined ? {} : options;
var size = options.size === undefined ? 'big' : options.size;
var cords = options.cords === undefined ? { x: 0, y: 0 } : options.cords;
var radius = options.radius === undefined ? 25 : options.radius;
console.log(size, cords, radius);
// now finally do some chart drawing
}
drawES5Chart({
cords: { x: 18, y: 30 },
radius: 30
});
ES6 version
function drawES6Chart({size = 'big', cords = { x: 0, y: 0 }, radius = 25} = {}) {
console.log(size, cords, radius);
// do some chart drawing
}
// In Firefox, default values for destructuring assignments are not yet implemented (as described below).
// The workaround is to write the parameters in the following way:
// ({size: size = 'big', cords: cords = { x: 0, y: 0 }, radius: radius = 25} = {})
drawES6Chart({
cords: { x: 18, y: 30 },
radius: 30
});
In Firefox, default values for destructuring assignments are not yet implemented: var { x = 3 } = {} and var [foo = "bar"] = []. See {{bug(932080)}} for destructured default values in functions.
Module (non-ES6) loading
Destructuring can help to load specific subsets of a non-ES6 module like here in the Add-on SDK:
const { Loader, main } = require('toolkit/loader');
The import statement in ES6 has a superficial resemablance to destructuring, but is actually completely unrelated.
Nested object and array destructuring
var metadata = {
title: "Scratchpad",
translations: [
{
locale: "de",
localization_tags: [ ],
last_edit: "2014-04-14T08:43:37",
url: "/de/docs/Tools/Scratchpad",
title: "JavaScript-Umgebung"
}
],
url: "/en-US/docs/Tools/Scratchpad"
};
var { title: englishTitle, translations: [{ title: localeTitle }] } = metadata;
console.log(englishTitle); // "Scratchpad"
console.log(localeTitle); // "JavaScript-Umgebung"
For of iteration and destructuring
var people = [
{
name: "Mike Smith",
family: {
mother: "Jane Smith",
father: "Harry Smith",
sister: "Samantha Smith"
},
age: 35
},
{
name: "Tom Jones",
family: {
mother: "Norah Jones",
father: "Richard Jones",
brother: "Howard Jones"
},
age: 25
}
];
for (var {name: n, family: { father: f } } of people) {
console.log("Name: " + n + ", Father: " + f);
}
// "Name: Mike Smith, Father: Harry Smith"
// "Name: Tom Jones, Father: Richard Jones"
Pulling fields from objects passed as function parameter
function userId({id}) {
return id;
}
function whois({displayName: displayName, fullName: {firstName: name}}){
console.log(displayName + " is " + name);
}
var user = {
id: 42,
displayName: "jdoe",
fullName: {
firstName: "John",
lastName: "Doe"
}
};
console.log("userId: " + userId(user)); // "userId: 42"
whois(user); // "jdoe is John"
This pulls the id, displayName and firstName from the user object and prints them.
Computed object property names and destructuring
Computed property names, like on object literals, can be used with destructuring.
let key = "z";
let { [key]: foo } = { z: "bar" };
console.log(foo); // "bar"
Specifications
| Specification | Status | Comment |
|---|---|---|
| {{SpecName('ES6', '#sec-destructuring-assignment', 'Destructuring assignment')}} | {{Spec2('ES6')}} | Initial definition. |
| {{SpecName('ESDraft', '#sec-destructuring-assignment', 'Destructuring assignment')}} | {{Spec2('ESDraft')}} |
Browser compatibility
| Feature | Chrome | Firefox (Gecko) | Edge | Internet Explorer | Opera | Safari |
|---|---|---|---|---|---|---|
| Basic support | {{CompatChrome(49.0)}} | {{ CompatGeckoDesktop("1.8.1") }} | 14 | {{CompatNo}} | {{CompatNo}} | 7.1 |
| Computed property names | {{CompatChrome(49.0)}} | {{ CompatGeckoDesktop("34") }} | 14 | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
| Spread operator | {{CompatChrome(49.0)}} | {{ CompatGeckoDesktop("34") }} | 12[1] | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} |
| Feature | Android | Chrome for Android | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile | Chrome for Android |
|---|---|---|---|---|---|---|---|
| Basic support | {{CompatNo}} | {{CompatChrome(49.0)}} | {{ CompatGeckoMobile("1.0") }} | {{CompatNo}} | {{CompatNo}} | 8 | {{CompatChrome(49.0)}} |
| Computed property names | {{CompatNo}} | {{CompatChrome(49.0)}} | {{ CompatGeckoMobile("34") }} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} | {{CompatChrome(49.0)}} |
| Spread operator | {{CompatNo}} | {{CompatChrome(49.0)}} | {{ CompatGeckoMobile("34") }} | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatChrome(49.0)}} |
[1] Requires "Enable experimental Javascript features" to be enabled under `about:flags`
Firefox-specific notes
- Firefox provided a non-standard language extension in JS1.7 for destructuring. This extension has been removed in Gecko 40 {{geckoRelease(40)}}. See {{bug(1083498)}}.
- Starting with Gecko 41 {{geckoRelease(41)}} and to comply with the ES6 specification, parenthesized destructuring patterns, like
([a, b]) = [1, 2]or({a, b}) = { a: 1, b: 2 }, are now considered invalid and will throw a {{jsxref("SyntaxError")}}. See Jeff Walden's blog post and {{bug(1146136)}} for more details.