JavaScript Object Destructuring: Complete Guide

JavaScript object destructuring is a shorthand syntax for extracting multiple properties from an object and assigning them to variables in one line. Instead of writing a separate line for every property you need, you list the property names inside curly braces on the left side of the assignment.

javascript

const user = { name: "Alex", age: 28, role: "admin" };
 
// Without destructuring
const name1 = user.name;
const age1 = user.age;
 
// With destructuring
const { name, age } = user;
 
console.log(name); // "Alex"
console.log(age);  // 28

The variable names must match the property names. JavaScript looks up each name inside the object and assigns the corresponding value.

Basic Syntax

The pattern is const { property1, property2 } = object. You list every property you want on the left, inside curly braces, and the source object on the right of the equals sign. You can extract as many properties as you need in a single statement:

javascript

const product = {
  id: 101,
  title: "Mechanical Keyboard",
  price: 89.99,
  inStock: true
};
 
const { title, price } = product;
 
console.log(title); // "Mechanical Keyboard"
console.log(price); // 89.99

Properties you do not list are simply ignored. The original object is not modified.

Default Values

When a property might be missing, provide a fallback value with the equals sign:

javascript

const config = { theme: "dark" };
 
const { theme, fontSize = 14 } = config;
 
console.log(theme);    // "dark"
console.log(fontSize); // 14 (default used)

The default only activates when the property is undefined. Other falsy values like 0, false, or an empty string are kept as-is:

javascript

const settings = { volume: 0, label: "" };
 
const { volume = 50, label = "Untitled" } = settings;
 
console.log(volume); // 0 (not undefined, so default not used)
console.log(label);  // "" (not undefined, so default not used)

Nested Destructuring

When an object contains another object, you can reach into the nested structure by mirroring the shape. This avoids writing out a chain of dot notation just to reach a value stored two or three levels deep:

javascript

const order = {
  id: 5001,
  customer: {
    name: "Jordan",
    address: { city: "Seattle", zip: "98101" }
  }
};
 
const { customer: { name } } = order;
 
console.log(name); // "Jordan"

The pattern customer: { name } means: go into the customer property, then extract name from it. The intermediate customer variable is never created unless you ask for it separately. The same idea extends to a third level:

javascript

const { customer: { address: { city } } } = order;
 
console.log(city); // "Seattle"

To keep the nested object itself and also pull a value out of it, use two separate destructuring statements instead of trying to do both in a single nested pattern:

javascript

const { customer } = order;
const { name } = customer;

Rest Pattern: Collecting Remaining Properties

Sometimes you only need a couple of properties by name but still want access to everything else. The rest pattern, written as ...rest, gathers all properties you did not explicitly name into a new object:

javascript

const book = {
  title: "Dune",
  author: "Frank Herbert",
  year: 1965,
  publisher: "Chilton"
};
 
const { title, author, ...details } = book;
 
console.log(details); // { year: 1965, publisher: "Chilton" }

The rest variable collects everything that was not destructured into its own object. This is useful when you need a few specific properties but want to pass the rest along.

Destructuring Function Parameters

One of the most practical uses of destructuring is in function signatures. Instead of accepting a long list of positional arguments, accept a single options object and destructure it:

javascript

function createUser({ name, email, role = "user" }) {
  console.log(name + " <" + email + "> is a " + role);
}
 
createUser({ name: "Sam", email: "sam@example.com" });
// "Sam <sam@example.com> is a user"
 
createUser({ name: "Alex", email: "alex@example.com", role: "admin" });
// "Alex <alex@example.com> is a admin"

This pattern is common in libraries and frameworks. The caller can pass properties in any order and omit optional ones.

Destructuring API Responses

Fetched data often arrives wrapped in a status field and a nested data object. Destructuring lets you skip straight to the values you actually need instead of writing out the full path every time:

javascript

const response = {
  status: "success",
  data: { user: { id: 1, name: "Priya" } }
};
 
const { data: { user } } = response;
 
console.log(user.name); // "Priya"

This keeps your code focused on the data you actually use, without temporary variables for every layer of the response. For transforming objects with key-value pairs, combining destructuring with /javascript/javascript-object-keys-values-and-entries-guide is a powerful pattern.

Common Mistakes

Forgetting that destructuring matches by name, not order. Array destructuring uses position; object destructuring uses property names:

javascript

const obj = { x: 10, y: 20 };
const { y, x } = obj; // Order does not matter
console.log(x, y);    // 10 20

Trying to destructure null or undefined. This throws a TypeError. Provide a default empty object when the source might be missing:

javascript

function printUser(user) {
  const { name } = user || {};
  console.log(name ?? "Unknown");
}

Confusing the rename syntax with a type annotation. const { name: userName } renames name to userName. It does not declare a type. For more on renaming, see the article on /javascript/renaming-variables-during-js-destructuring-guide.