The object and array literal expressions provide an easy way to createad hoc packages of data.

const arr = [a, b, c];

The destructuring uses similar syntax but uses it on the left-hand side of the assignment instead. It performs the reverse operation of an array declaration, by declaring each element in the collection as a separate variable.

const arr = [1, 2, 3];const [a, b, c] = arr;// a = 1, b = 2, c = 3

As for objects, compare the two pairs of lines below, and see how there's a direct correspondence within each pair.

const obj = { a, b, c };const { a, b, c } = obj;// Equivalent to:// const a = obj.a, b = obj.b, c = obj.c;const obj = { prop1: x, prop2: y, prop3: z };const { prop1: x, prop2: y, prop3: z } = obj;// Equivalent to:// const x = obj.prop1, y = obj.prop2, z = obj.prop3;

This capability is similar to features present in languages such as Perl and Python.

For features specific to array or object destructuring, refer to the individualexamples below.

For both object and array destructuring, there are two kinds of destructuring patterns:binding pattern andassignment pattern, with slightly different syntaxes.

In binding patterns, the pattern starts with a declaration keyword (var,let, orconst). Then, each individual property must either be bound to a variable or further destructured.

const obj = { a: 1, b: { c: 2 } };const {  a,  b: { c: d },} = obj;// Two variables are bound: `a` and `d`

All variables share the same declaration, so if you want some variables to be re-assignable but others to be read-only, you may have to destructure twice — once withlet, once withconst.

const obj = { a: 1, b: { c: 2 } };const { a } = obj; // a is constantlet {  b: { c: d },} = obj; // d is re-assignable

In many other syntaxes where the language binds a variable for you, you can use a binding destructuring pattern. These include:

• The looping variable offor...infor...of, andfor await...of loops;
• Function parameters;
• Thecatch binding variable.

In assignment patterns, the pattern does not start with a keyword. Each destructured property is assigned to a target of assignment — which may either be declared beforehand withvar orlet, or is a property of another object — in general, anything that can appear on the left-hand side of an assignment expression.

const numbers = [];const obj = { a: 1, b: 2 };({ a: numbers[0], b: numbers[1] } = obj);// The properties `a` and `b` are assigned to properties of `numbers`

Note that the equivalentbinding pattern of the code above is not valid syntax:

const numbers = [];const obj = { a: 1, b: 2 };const { a: numbers[0], b: numbers[1] } = obj;// This is equivalent to://   const numbers[0] = obj.a;//   const numbers[1] = obj.b;// Which definitely is not valid.

You can only use assignment patterns as the left-hand side of theassignment operator. You cannot use them with compound assignment operators such as+= or*=.

Each destructured property can have adefault value. The default value is used when the property is not present, or has valueundefined. It is not used if the property has valuenull.

const [a = 1] = []; // a is 1const { b = 2 } = { b: undefined }; // b is 2const { c = 2 } = { c: null }; // c is null

The default value can be any expression. It will only be evaluated when necessary.

const { b = console.log("hey") } = { b: 2 };// Does not log anything, because `b` is defined and there's no need// to evaluate the default value.

You can end a destructuring pattern with a rest property...rest. For array destructuring, it collects remaining elements of the iterable into a new array calledrest (or any name you give it). For object destructuring, it copies all enumerable own properties of the object that are not already picked off by the destructuring pattern into a new object calledrest.

More formally, the...rest syntax is called "rest elements" in array destructuring and "rest properties" in object destructuring, but we often just collectively call them "rest property".

const { a, ...others } = { a: 1, b: 2, c: 3 };console.log(others); // { b: 2, c: 3 }const [first, ...others2] = [1, 2, 3];console.log(others2); // [2, 3]

The rest property must be the last in the pattern, and must not have a trailing comma.

const [a, ...b,] = [1, 2, 3];// SyntaxError: rest element may not have a trailing comma// Always consider using rest operator as the last element

Basic variable assignment

const foo = ["one", "two", "three"];const [red, yellow, green] = foo;console.log(red); // "one"console.log(yellow); // "two"console.log(green); // "three"

Destructuring with more elements than the source

In an array destructuring from an array of lengthN specified on the right-hand side of the assignment, if the number of variables specified on the left-hand side of the assignment is greater thanN, only the firstN variables are assigned values. The values of the remaining variables will be undefined.

const foo = ["one", "two"];const [red, yellow, green, blue] = foo;console.log(red); // "one"console.log(yellow); // "two"console.log(green); // undefinedconsole.log(blue); // undefined

Swapping variables

Two variables values can be swapped in one destructuring expression.

Without destructuring, swapping two values requires a temporary variable (or, in some low-level languages, theXOR-swap trick).

let a = 1;let b = 3;[a, b] = [b, a];console.log(a); // 3console.log(b); // 1const arr = [1, 2, 3];[arr[2], arr[1]] = [arr[1], arr[2]];console.log(arr); // [1, 3, 2]

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];}const [a, b] = f();console.log(a); // 1console.log(b); // 2

Ignoring some returned values

You can ignore return values that you're not interested in:

function f() {  return [1, 2, 3];}const [a, , b] = f();console.log(a); // 1console.log(b); // 3const [c] = f();console.log(c); // 1

You can also ignore all returned values:

[, ,] = f();

Though in this case, it's probably clearer to just call the function and not use destructuring at all. You don't have to use the return value.

Using a binding pattern as the rest property

The rest property of array destructuring can be another array or object binding pattern. The inner destructuring destructures from the array created after collecting the rest elements, so you cannot access any properties present on the original iterable in this way.

const [a, b, ...{ length }] = [1, 2, 3];console.log(a, b, length); // 1 2 1

const [a, b, ...[c, d]] = [1, 2, 3, 4];console.log(a, b, c, d); // 1 2 3 4

These binding patterns can even be nested, as long as each rest property is the last in the list.

const [a, b, ...[c, d, ...[e, f]]] = [1, 2, 3, 4, 5, 6];console.log(a, b, c, d, e, f); // 1 2 3 4 5 6

On the other hand, object destructuring can only have an identifier as the rest property.

const { a, ...{ b } } = { a: 1, b: 2 };// SyntaxError: `...` must be followed by an identifier in declaration contextslet a, b;({ a, ...{ b } } = { a: 1, b: 2 });// SyntaxError: `...` must be followed by an assignable reference in assignment contexts

Unpacking values from a regular expression match

When the regular expressionexec() 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 allows you to unpack the parts out of this array easily, ignoring the full match if it is not needed.

function parseProtocol(url) {  const parsedURL = /^(\w+):\/\/([^/]+)\/(.*)$/.exec(url);  if (!parsedURL) {    return false;  }  console.log(parsedURL);  // ["https://developer.mozilla.org/en-US/docs/Web/JavaScript",  // "https", "developer.mozilla.org", "en-US/docs/Web/JavaScript"]  const [, protocol, fullHost, fullPath] = parsedURL;  return protocol;}console.log(  parseProtocol("https://developer.mozilla.org/en-US/docs/Web/JavaScript"),);// "https"

Using array destructuring on any iterable

Array destructuring calls theiterable protocol of the right-hand side. Therefore, any iterable, not necessarily arrays, can be destructured.

const [a, b] = new Map([  [1, 2],  [3, 4],]);console.log(a, b); // [1, 2] [3, 4]

Non-iterables cannot be destructured as arrays.

const obj = { 0: "a", 1: "b", length: 2 };const [a, b] = obj;// TypeError: obj is not iterable

Iterables are only iterated until all bindings are assigned.

const obj = {  *[Symbol.iterator]() {    for (const v of [0, 1, 2, 3]) {      console.log(v);      yield v;    }  },};const [a, b] = obj; // Only logs 0 and 1

The rest binding is eagerly evaluated and creates a new array, instead of using the old iterable.

const obj = {  *[Symbol.iterator]() {    for (const v of [0, 1, 2, 3]) {      console.log(v);      yield v;    }  },};const [a, b, ...rest] = obj; // Logs 0 1 2 3console.log(rest); // [2, 3] (an array)

Basic assignment

const user = {  id: 42,  isVerified: true,};const { id, isVerified } = user;console.log(id); // 42console.log(isVerified); // true

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.

const o = { p: 42, q: true };const { p: foo, q: bar } = o;console.log(foo); // 42console.log(bar); // true

Here, for example,const { p: foo } = o takes from the objecto the property namedp and assigns it to a local variable namedfoo.

Assigning to new variable names and providing default values

A property can be both

• Unpacked from an object and assigned to a variable with a different name.
• Assigned a default value in case the unpacked value isundefined.

const { a: aa = 10, b: bb = 5 } = { a: 3 };console.log(aa); // 3console.log(bb); // 5

Unpacking properties from objects passed as a function parameter

Objects passed into function parameters can also be unpacked into variables, which may then be accessed within the function body.As for object assignment, the destructuring syntax allows for the new variable to have the same name or a different name than the original property, and to assign default values for the case when the original object does not define the property.

Consider this object, which contains information about a user.

const user = {  id: 42,  displayName: "jdoe",  fullName: {    firstName: "Jane",    lastName: "Doe",  },};

Here we show how to unpack a property of the passed object into a variable with the same name.The parameter value{ id } indicates that theid property of the object passed to the function should be unpacked into a variable with the same name, which can then be used within the function.

function userId({ id }) {  return id;}console.log(userId(user)); // 42

You can define the name of the unpacked variable.Here we unpack the property nameddisplayName, and rename it todname for use within the function body.

function userDisplayName({ displayName: dname }) {  return dname;}console.log(userDisplayName(user)); // "jdoe"

Nested objects can also be unpacked.The example below shows the propertyfullname.firstName being unpacked into a variable calledname.

function whois({ displayName, fullName: { firstName: name } }) {  return `${displayName} is ${name}`;}console.log(whois(user)); // "jdoe is Jane"

Setting a function parameter's default value

Default values can be specified using=, and will be used as variable values if a specified property does not exist in the passed object.

Below we show a function where the default size is'big', default co-ordinates arex: 0, y: 0 and default radius is 25.

function drawChart({  size = "big",  coords = { x: 0, y: 0 },  radius = 25,} = {}) {  console.log(size, coords, radius);  // do some chart drawing}drawChart({  coords: { x: 18, y: 30 },  radius: 30,});

In the function signature fordrawChart above, the destructured left-hand side has a default value of an empty object= {}.

You could have also written the function without that default. However, if you leave out that default value, the function will look for at least one argument to be supplied when invoked, whereas in its current form, you can calldrawChart() without supplying any parameters. Otherwise, you need to at least supply an empty object literal.

For more information, seeDefault parameters > Destructured parameter with default value assignment.

Nested object and array destructuring

const metadata = {  title: "Scratchpad",  translations: [    {      locale: "de",      localizationTags: [],      lastEdit: "2014-04-14T08:43:37",      url: "/de/docs/Tools/Scratchpad",      title: "JavaScript-Umgebung",    },  ],  url: "/en-US/docs/Tools/Scratchpad",};const {  title: englishTitle, // rename  translations: [    {      title: localeTitle, // rename    },  ],} = metadata;console.log(englishTitle); // "Scratchpad"console.log(localeTitle); // "JavaScript-Umgebung"

For of iteration and destructuring

const 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 (const {  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"

Computed object property names and destructuring

Computed property names, like onobject literals, can be used with destructuring.

const key = "z";const { [key]: foo } = { z: "bar" };console.log(foo); // "bar"

Invalid JavaScript identifier as a property name

Destructuring can be used with property names that are not valid JavaScriptidentifiers by providing an alternative identifier that is valid.

const foo = { "fizz-buzz": true };const { "fizz-buzz": fizzBuzz } = foo;console.log(fizzBuzz); // true

Object destructuring is almost equivalent toproperty accessing. This means if you try to destruct a primitive value, the value will get wrapped into the corresponding wrapper object and the property is accessed on the wrapper object.

const { a, toFixed } = 1;console.log(a, toFixed); // undefined ƒ toFixed() { [native code] }

Same as accessing properties, destructuringnull orundefined throws aTypeError.

const { a } = undefined; // TypeError: Cannot destructure property 'a' of 'undefined' as it is undefined.const { b } = null; // TypeError: Cannot destructure property 'b' of 'null' as it is null.

This happens even when the pattern is empty.

const {} = null; // TypeError: Cannot destructure 'null' as it is null.

Combined array and object destructuring

Array and object destructuring can be combined. Say you want the third element in the arrayprops below, and then you want thename property in the object, you can do the following:

const props = [  { id: 1, name: "Fizz" },  { id: 2, name: "Buzz" },  { id: 3, name: "FizzBuzz" },];const [, , { name }] = props;console.log(name); // "FizzBuzz"

The prototype chain is looked up when the object is deconstructed

When deconstructing an object, if a property is not accessed in itself, it will continue to look up along the prototype chain.

const obj = {  self: "123",  __proto__: {    prot: "456",  },};const { self, prot } = obj;console.log(self); // "123"console.log(prot); // "456"

• Assignment operators
• ES6 in Depth: Destructuring on hacks.mozilla.org (2015)