JavaScript Destructuring Explained: Objects, Arrays, Defaults and Common Errors

An API returns a user object, and you need the name, the city and the first tag. Without destructuring, that is three lines of user.something. With it, one readable line pulls out exactly what you need. Destructuring arrived in ES2015 (ES6), and it now appears everywhere from React components to Node.js route handlers.

We ran every snippet in Node.js 24, and the outputs shown are from that run. The same syntax works in all modern browsers.

What is destructuring?

Destructuring is a syntax for unpacking values from objects or arrays into separate variables. The pattern on the left of the = mirrors the shape of the data on the right. Curly braces {} mean “take properties from an object”, and square brackets [] mean “take items from an array”.

Object destructuring

const user = {
  id: 7,
  name: "Asha",
  address: { city: "Pune", pin: "411001" },
  tags: ["admin", "beta"],
};

const { name, id } = user;
console.log(name, id);   // Asha 7

The variable names must match the property names, but the order does not matter. We asked for name before id, even though id comes first in the object. A property that does not exist simply gives undefined.

Renaming and defaults

Use a colon to store a property under a different variable name, and = to give a fallback value:

const { name: fullName, role = "viewer" } = user;
console.log(fullName, role);   // Asha viewer

Read name: fullName as “take name and call it fullName“. Renaming is useful when two objects have properties with the same name, or when a property name is not a valid variable name in your context.

Here is the subtle part. A default is used only when the value is undefined:

const { role: r2 = "viewer" } = { role: null };
console.log(r2);   // null

The property existed and was null, so the default was ignored. APIs often send null for “no value”, so if you want a fallback in both cases, use the nullish coalescing operator afterwards: const role = data.role ?? "viewer".

Nested patterns

Patterns can go as deep as the data:

const { address: { city }, tags: [firstTag] } = user;
console.log(city, firstTag);   // Pune admin

This creates only city and firstTag. It does not create variables called address or tags, which surprises people the first time. Keep nesting to one or two levels; deeper patterns become harder to read than plain property access.

The rest pattern

Three dots collect everything you did not name into a new object or array:

const { id: _id, ...rest } = user;
console.log(Object.keys(rest));   // [ 'name', 'address', 'tags' ]

This is a clean way to remove a property without changing the original object. For example, you might strip a password hash before sending a user to the browser. The rest element must come last in the pattern.

Array destructuring

With arrays, position is what matters. You can skip items with empty commas, give defaults and collect the rest:

const [a, , c = "none", ...others] = [1, 2, undefined, 4, 5];
console.log(a, c, others);   // 1 none [ 4, 5 ]

The second item was skipped, the third was undefined so its default applied, and the remaining items went into others.

Swapping variables

let x = 1, y = 2;
[x, y] = [y, x];
console.log(x, y);   // 2 1

No temporary variable is needed. Array destructuring also works with anything iterable, including strings, Sets and Maps, which we use in the loops section below.

Function parameters

Destructuring in a parameter list lets a function accept an options object with clear names and defaults:

function greet({ name, greeting = "Hello" } = {}) {
  return `${greeting}, ${name ?? "guest"}`;
}
console.log(greet({ name: "Ben" }), "|", greet());
// Hello, Ben | Hello, guest

The = {} at the end matters. Without it, calling greet() with no argument would try to destructure undefined and throw. Options objects like this are easier to extend than long lists of positional arguments, because callers name what they pass and can skip the rest. Our post on JavaScript closures uses the same pattern for factory functions.

Loops, entries and Maps

for (const [key, value] of Object.entries({ pen: 10, book: 250 })) {
  console.log(key, value);
}
// pen 10
// book 250

const map = new Map([["a", 1]]);
for (const [k, v] of map) console.log(k, v);   // a 1

Object.entries() returns key-value pairs as small arrays, and array destructuring unpacks each pair. The same trick works with array methods such as map and filter, as in users.map(({ name }) => name).

Computed property names

const key = "name";
const { [key]: dynamic } = user;
console.log(dynamic);   // Asha

When the property name is only known at runtime, put it in square brackets and give the variable a name with a colon.

Errors and traps

Destructuring from null or undefined throws immediately. We hit both cases:

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

const { missing: { deep } } = user;
// TypeError: Cannot read properties of undefined (reading 'deep')

The second case is common with nested API data, where one level is sometimes missing. Give the nested level a default, as in const { missing: { deep } = {} } = user, or use optional chaining, user.missing?.deep, which is often clearer.

Assigning to existing variables

let n1, n2;
({ n1, n2 } = { n1: 10, n2: 20 });
console.log(n1, n2);   // 10 20

When the line starts with {, JavaScript reads it as a block of code, not a pattern. Wrapping the whole assignment in parentheses fixes it. If the previous line has no semicolon, add one before the parenthesis, or the two lines may be joined.

Destructuring and spread are not deep copies

The rest pattern and the spread operator copy only the top level. Nested objects are still shared:

const copy = { ...user };
copy.address.city = "Delhi";
console.log(user.address.city);   // Delhi

Changing the copy’s address changed the original, because both point to the same address object. For a true deep copy of plain data, use structuredClone(user), which is built into modern browsers and Node.js. This shared-reference behaviour is a frequent cause of state bugs in front-end apps.

Real-world uses

• React props and hooks: function Card({ title, children }) and const [count, setCount] = useState(0) are both destructuring. We simulated the hook pattern with a small function, and count was 0 and setCount a function.
• API responses: const { data, error } = await res.json(), as shown in our Fetch API guide.
• Module imports: import { readFile } from "node:fs/promises" looks like destructuring and is used the same way, though it is technically a separate syntax.
• Returning several values: return an object, { total, count }, and destructure it at the call site.

Destructuring in TypeScript

TypeScript adds one common trap. A colon inside a destructuring pattern means “rename”, not “type”, so this does not do what it looks like:

// Looks like a type, but renames name to a variable called string
function greet({ name: string }) { ... }

The type goes after the whole pattern instead:

function greet({ name, greeting = "Hello" }: { name: string; greeting?: string }) {
  return `${greeting}, ${name}`;
}

// Clearer with a named type
type GreetOptions = { name: string; greeting?: string };
function greet2({ name, greeting = "Hello" }: GreetOptions) { ... }

Naming the type keeps the function signature readable and lets other code reuse it. With strict mode on, TypeScript also checks that defaults match the declared types. These snippets are illustrations and were not compiled for this article; our interface vs type guide shows compiler output for similar shapes.

Final thoughts

Destructuring is one of the most useful pieces of modern JavaScript. Remember the two rules, names for objects and positions for arrays, and the two traps, defaults ignore null and destructuring null throws. Use it to make intent clear at the top of a function, and keep patterns shallow enough that a teammate can read them in one glance.

Frequently asked questions

Keep learning