JavaScript Reference ยท Operators
Destructuring assignment
Reference for JavaScript destructuring: unpacking arrays and objects, defaults, renaming, nested patterns, rest elements, swapping and parameter destructuring.
Destructuring is syntax that unpacks values from an array (or any iterable) or properties from an object into separate variables, using a pattern that looks like the literal you would write to build that value. It works in declarations (const, let, var), in plain assignments, in function parameters, in for...of heads and in catch clauses.
Array patterns match by position and use the iteration protocol. Object patterns match by property name.
const [first, second] = list; const { name, age } = person;
Try it
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Syntax
const [a, b = 1, ...rest] = iterable; const { a, b = 1, c: renamed, ...rest } = object; const { a: { b }, d: [e] } = nested; [a, b] = [b, a]; // assignment form ({ a, b } = object); // object assignment form needs parentheses function f({ a, b } = {}, [c, d] = []) {}
| Part | Description |
|---|---|
[a, b] |
Array pattern: assigns the first and second values from the iterator. Missing values become undefined. |
[, b] |
An empty slot skips one element. |
a = default |
Default value, used only when the value is undefined. |
{ key } |
Shorthand for { key: key }: takes source.key and stores it in a variable named key. |
{ key: name } |
Reads source.key and stores it in a variable called name. |
{ [expr]: name } |
Computed property key. |
...rest |
Collects the remaining elements (a new array) or the remaining own enumerable properties (a new object). Must be last, with no trailing comma. |
Return value: a destructuring assignment expression evaluates to the right-hand side value, not to the variables.
Exceptions: destructuring null or undefined with an object pattern throws a TypeError. An array pattern on a non-iterable (including a plain object) throws a TypeError.
Usage notes
- Defaults are lazy. The default expression runs only if the value is
undefined, and it can refer to earlier variables in the same pattern. nullis notundefined. A property that holdsnulldoes not trigger its default; combine with??after destructuring if you need that.- Nested patterns are strict. If
addressis missing,{ address: { city } }throws because it tries to destructureundefined. Give the inner part a default:{ address: { city } = {} }. - Object patterns read inherited properties too, since they use ordinary property access. Rest elements, by contrast, copy only own enumerable properties.
- Parameter default
= {}makes the whole argument optional; without it, callingdescribe()would throw. - Statement start. A line beginning with
{is a block, so wrap an object assignment in parentheses and keep the semicolon on the previous line. - Array patterns consume iterators lazily. Destructuring
[a, b]from a generator reads only two values. - Copies are shallow. Destructured object values still refer to the same nested objects.
Browser support
Supported in every current browser (ES2015). Object rest in patterns arrived later (ES2018) and is also available in current browsers.