Skip to main content

How to Add a Key-Value Pair to an Object in JavaScript

Adding a new property (a key-value pair) to an existing object is one of the most fundamental operations in JavaScript. Whether you are building an object from scratch or dynamically updating it, there are several simple and effective ways to accomplish this.

This guide will teach you the two primary methods for adding properties to an object: the direct dot and bracket notation, and the modern, immutable approach using the spread syntax (...).

The Core Method: Direct Property Assignment​

This is the most common and straightforward way to add or update a property on an object. You are directly mutating the object.

Using Dot Notation​

Use dot notation when the key is a valid JavaScript identifier (e.g., contains no spaces or special characters).

For example, you have an object and need to add a new property to it.

// Problem: How to add an `age` property to this object?
const user = { name: 'Alice' };

Solution:

const user = { name: 'Alice' };

// Add a new property using dot notation
user.age = 30;

// If the property already exists, this will update its value
user.name = 'Alicia';

console.log(user);

Output:

{ name: 'Alicia', age: 30 }

Using Bracket Notation (for Dynamic Keys)​

You must use bracket notation when the key is a variable or a string that is not a valid identifier (e.g., contains spaces or hyphens).

Solution:

const user = {};
const keyName = 'country';

// Use bracket notation when the key is stored in a variable
user[keyName] = 'Canada';

// Use bracket notation for keys with special characters
user['full-name'] = 'Alice Smith';

console.log(user);

Output:

{ country: 'Canada', 'full-name': 'Alice Smith' }

The Modern Method (Recommended): Spread Syntax (...)​

In modern JavaScript, it is often a best practice to treat objects as immutable, meaning you should create a new object with the updated properties instead of changing the original one. The spread syntax (...) is the perfect tool for this.

The logic: the spread syntax unpacks the properties from an existing object into a new object literal, allowing you to add new properties or override existing ones.

Solution:

const originalUser = { name: 'Alice' };

// Create a NEW object with the properties of the original, plus a new one
const updatedUser = {
  ...originalUser,
  age: 30,
};

console.log(updatedUser);    // Output: { name: 'Alice', age: 30 }
console.log(originalUser);   // Output: { name: 'Alice' } (The original is unchanged)

// You can also override existing properties
const overriddenUser = {
  ...originalUser,
  name: 'Alicia', // This will override the original 'name'
};
console.log(overriddenUser); // Output: { name: 'Alicia' }

Output:

{name: 'Alice', age: 30}
{name: 'Alice'}
{name: 'Alicia'}
note

This is the recommended best practice for its readability and for avoiding unintended side effects by not mutating data.

How to Add a Property to the Beginning of an Object​

While the order of object properties is not guaranteed in all JavaScript environments (though it is predictable in modern ones), you can control the initial order by using the spread syntax.

The solution is to add a new property at the beginning, placing it before the spread operator.

const originalUser = { name: 'Alice', age: 30 };

const newUser = {
  id: 1,
  ...originalUser,      // The original properties will be added after 'id'
};

console.log(newUser);   // Output: { id: 1, name: 'Alice', age: 30 }

Output:

{ id: 1, name: 'Alice', age: 30 }
note

Properties are added in the order they appear in the object literal. If a key already exists in the spread object, the last one defined wins, so to override a value, place the new property after the spread.

Conclusion​

Adding a key-value pair to an object in JavaScript is a simple task with clear, modern solutions.

  • For quick and direct mutation, use dot notation (obj.key = ...) for static keys or bracket notation (obj[key] = ...) for dynamic keys.
  • The recommended best practice for modern, immutable code is to use the spread syntax (...) to create a new object with the added or updated properties: const newObj = { ...oldObj, newKey: 'newValue' };
  • The spread syntax also gives you easy control over the property order in the new object.

Table of Contents