Line Value Assignment
The destructuring assignment syntax is a JavaScript expression that makes it possible to unpack values from arrays, or properties from objects, into distinct variables.
The source for this interactive example is stored in a GitHub repository. If you'd like to contribute to the interactive examples project, please clone https://github.com/mdn/interactive-examples and send us a pull request.
Syntax
var a, b, rest; [a, b] = [10, 20]; console.log(a); // 10 console.log(b); // 20 [a, b, ...rest] = [10, 20, 30, 40, 50]; console.log(a); // 10 console.log(b); // 20 console.log(rest); // [30, 40, 50] ({ a, b } = { a: 10, b: 20 }); console.log(a); // 10 console.log(b); // 20 // Stage 3 proposal ({a, b, ...rest} = {a: 10, b: 20, c: 30, d: 40}); console.log(a); // 10 console.log(b); // 20 console.log(rest); //{c: 30, d: 40}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 values to unpack from the sourced variable.
var x = [1, 2, 3, 4, 5]; var [y, z] = x; console.log(y); // 1 console.log(z); // 2This 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); // 2Default values
A variable can be assigned a default, in the case that the value unpacked from the array is .
var a, b; [a=5, b=7] = [1]; console.log(a); // 1 console.log(b); // 7Swapping 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); // 1Parsing 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, returns the values 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); // 2Ignoring 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); // 3You can also ignore all returned values:
[,,] = f();Assigning the rest of an array to a variable
When destructuring an array, you can unpack and assign the remaining part of it to a variable using the rest pattern:
var [a, ...b] = [1, 2, 3]; console.log(a); // 1 console.log(b); // [2, 3]Note that a will be thrown if a trailing comma is used on the left-hand side with a rest element:
var [a, ...b,] = [1, 2, 3]; // SyntaxError: rest element may not have a trailing commaUnpacking values from a regular expression match
When the regular expression 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 unpack the parts out of this array easily, ignoring the full match if it is not needed.
function parseProtocol(url) { var parsedURL = /^(\w+)\:\/\/([^\/]+)\/(.*)$/.exec(url); if (!parsedURL) { return false; } console.log(parsedURL); // ["https://developer.mozilla.org/en-US/Web/JavaScript", "https", "developer.mozilla.org", "en-US/Web/JavaScript"] var [, protocol, fullhost, fullpath] = parsedURL; return protocol; } console.log(parseProtocol('https://developer.mozilla.org/en-US/Web/JavaScript')); // "https"Object destructuring
Basic assignment
var o = {p: 42, q: true}; var {p, q} = o; console.log(p); // 42 console.log(q); // trueAssignment 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 round braces around the assignment statement is required syntax when using object literal destructuring assignment without a declaration.
is not valid stand-alone syntax, as the on the left-hand side is considered a block and not an object literal.
However, is valid, as is
Assigning to new variable names
A property can be unpacked 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); // trueDefault values
A variable can be assigned a default, in the case that the value unpacked from the object is .
var {a = 10, b = 5} = {a: 3}; console.log(a); // 3 console.log(b); // 5Assigning to new variables names and providing default values
A property can be both 1) unpacked from an object and assigned to a variable with a different name and 2) assigned a default value in case the unpacked value is .
var {a:aa = 10, b:bb = 5} = {a: 3}; console.log(aa); // 3 console.log(bb); // 5Setting 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 });ES2015 version
function drawES2015Chart({size = 'big', cords = {x: 0, y: 0}, radius = 25} = {}) { console.log(size, cords, radius); // do some chart drawing } drawES2015Chart({ cords: {x: 18, y: 30}, radius: 30 });In the function signature for above, the destructured left-hand side is assigned to an empty object literal on the right-hand side: . You could have also written the function without the right-hand side assignment. However, if you leave out the right-hand side assignment, the function will look for at least one argument to be supplied when invoked, whereas in its current form, you can simply call without supplying any parameters. The current design is useful if you want to be able to call the function without supplying any parameters, the other can be useful when you want to ensure an object is passed to the function.
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"Unpacking fields from objects passed as function parameter
function userId({id}) { return id; } function whois({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 unpacks the , and 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"Rest in Object Destructuring
The Rest/Spread Properties for ECMAScript proposal (stage 3) adds the rest syntax to destructuring. Rest properties collect the remaining own enumerable property keys that are not already picked off by the destructuring pattern.
let {a, b, ...rest} = {a: 10, b: 20, c: 30, d: 40} a; // 10 b; // 20 rest; // { c: 30, d: 40 }Invalid JavaScript identifier as a property name
Destructuring can be used with property names that are not valid JavaScript identifiers by providing an alternative identifer that is valid.
const foo = { 'fizz-buzz': true }; const { 'fizz-buzz': fizzBuzz } = foo; console.log(fizzBuzz); // "true"Specifications
Browser compatibility
The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.
Feature | Chrome | Edge | Firefox | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|---|
Basic support | 49 | 14 | 411 | No | Yes | 8 |
Computed property names | 49 | 14 | 34 | No | Yes | No |
Rest in arrays | 49 | 142 | 34 | No | Yes | No |
Rest in objects | 60 | No | 55 | No | Yes | No |
Feature | Android webview | Chrome for Android | Edge mobile | Firefox for Android | Opera Android | iOS Safari | Samsung Internet |
---|---|---|---|---|---|---|---|
Basic support | 49 | 49 | 14 | 411 | Yes | 8 | ? |
Computed property names | 49 | 49 | 14 | 34 | Yes | No | ? |
Rest in arrays | 49 | 49 | 142 | 34 | Yes | No | ? |
Rest in objects | 60 | 60 | No | 55 | Yes | No | ? |
1. Firefox provided a non-standard destructuring implementation from Firefox 2 to 40.
2. From version 14: this feature is behind the preference.
Desktop | Mobile | Server | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Chrome | Edge | Firefox | Internet Explorer | Opera | Safari | Android webview | Chrome for Android | Edge Mobile | Firefox for Android | Opera for Android | iOS Safari | Samsung Internet | Node.js | |
Basic support | Full support 49 | Full support 14 | Full support 41 Notes
| No support No | Full support Yes | Full support 8 | Full support 49 | Full support 49 | Full support 14 | Full support 41 Notes
| Full support Yes | Full support 8 | ? | Full support Yes |
Computed property names | Full support 49 | Full support 14 | Full support 34 | No support No | Full support Yes | No support No | Full support 49 | Full support 49 | Full support 14 | Full support 34 | Full support Yes | No support No | ? | Full support Yes |
Rest in arrays | Full support 49 | Full support 14 Disabled
| Full support 34 | No support No | Full support Yes | No support No | Full support 49 | Full support 49 | Full support 14 Disabled
| Full support 34 | Full support Yes | No support No | ? | Full support Yes |
Rest in objects Experimental | Full support 60 | No support No | Full support 55 | No support No | Full support Yes | No support No | Full support 60 | Full support 60 | No support No | Full support 55 | Full support Yes | No support No | ? | Full support Yes |
Legend
- Full support
- Full support
- No support
- No support
- Compatibility unknown
- Compatibility unknown
- Experimental. Expect behavior to change in the future.
- Experimental. Expect behavior to change in the future.
- See implementation notes.
- See implementation notes.
- User must explicitly enable this feature.
- User must explicitly enable this feature.
See also
Tuple Assignment with unpacking¶
Python has a very powerful tuple assignment feature that allows a tuple of variable names on the left of an assignment statement to be assigned values from a tuple on the right of the assignment. Another way to think of this is that the tuple of values is unpacked into the variable names.
This does the equivalent of seven assignment statements, all on one easy line. One requirement is that the number of variables on the left must match the number of elements in the tuple.
Once in a while, it is useful to swap the values of two variables. With conventional assignment statements, we have to use a temporary variable. For example, to swap and :
Tuple assignment solves this problem neatly:
The left side is a tuple of variables; the right side is a tuple of values. Each value is assigned to its respective variable. All the expressions on the right side are evaluated before any of the assignments. This feature makes tuple assignment quite versatile.
Naturally, the number of variables on the left and the number of values on the right have to be the same.
Python even provides a way to pass a single tuple to a function and have it be unpacked for assignment to the named parameters.
(cp09_tuple4)
If you run this, you will be get an error caused by line 7, where it says that the function add is expecting two parameters, but you’re only passing one parameter (a tuple). In line 6 you’ll see that the tuple is unpacked and 5 is bound to x, 4 to y.
Don’t worry about mastering this idea yet. But later in the course, if you come across some code that someone else has written that uses the * notation inside a parameter list, come back and look at this again.
keyword-params-92: Consider the following alternative way to swap the values of variables x and y. What’s wrong with it?
One thought on “Line Value Assignment”