Object.freeze()

freeze(obj)

Returns: object · Added in vES5 · Updated March 15, 2026 · Object Methods

object freeze immutable prevent modifications

The Object.freeze() method makes an object completely immutable—you can’t add, remove, or modify any properties. It returns the same object that was passed in (not a copy).

Syntax

Object.freeze(obj)

Parameters

Parameter	Type	Default	Description
`obj`	`object`	—	The object to freeze.

Return Value

Returns the object that was passed in (not a copy).

Examples

Basic freeze usage

const config = {
  apiUrl: 'https://api.example.com',
  timeout: 5000
};

Object.freeze(config);

// These operations all fail silently in non-strict mode
config.apiUrl = 'https://other.com';   // Ignored
config.newProp = 'value';             // Ignored
delete config.timeout;                // Ignored

// In strict mode, each would throw a TypeError
console.log(config.apiUrl);  // 'https://api.example.com'

// Verify frozen state
Object.isFrozen(config);     // true

The frozen object retains its original values. Any attempt to modify it fails without warning in sloppy mode, but throws in strict mode.

Freeze vs Seal Comparison

const frozen = Object.freeze({ value: 1 });

// Frozen: can't change values
frozen.value = 2;
console.log(frozen.value);  // 1

// Can't add new properties
frozen.newProp = 'x';
console.log(frozen.newProp);  // undefined

Common Patterns

Configuration constants:

const APP_CONFIG = Object.freeze({
  VERSION: '1.0.0',
  MAX_RETRIES: 3,
  API_BASE: 'https://api.app.com'
});

// Attempting to modify throws in strict mode
// Great for values that should never change

Deep freezing for nested objects:

function deepFreeze(obj) {
  Object.freeze(obj);
  
  for (const key of Object.keys(obj)) {
    if (obj[key] && typeof obj[key] === 'object') {
      deepFreeze(obj[key]);
    }
  }
  return obj;
}

const data = {
  user: { name: 'Alice' },
  settings: { theme: 'dark' }
};

deepFreeze(data);
data.user.name = 'Bob';          // Fails
data.settings.theme = 'light';   // Fails

Caveats

Shallow freeze only:

const obj = {
  nested: { value: 1 }
};

Object.freeze(obj);
obj.nested.value = 2;  // This works! Nested objects aren't frozen

console.log(obj.nested.value);  // 2

A simple Object.freeze() doesn’t affect nested objects. You need deep freezing for that.

Arrays are also affected:

const arr = [1, 2, 3];
Object.freeze(arr);

arr.push(4);        // TypeError in strict mode
arr[0] = 99;        // Fails
arr.length = 10;   // Fails

Freezing arrays prevents any modification to their contents or length.