Skip to content
Tutorials Center
My learning

Topics

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.

JavaScript
const [first, second] = list;
const { name, age } = person;

Try it

JS Arrays and objects

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Parameters, defaults and iterables

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Syntax

JavaScript
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.
  • null is not undefined. A property that holds null does not trigger its default; combine with ?? after destructuring if you need that.
  • Nested patterns are strict. If address is missing, { address: { city } } throws because it tries to destructure undefined. 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, calling describe() 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.