JavaScript Reflect.defineProperty() Method

Beginner
6 min read
Updated: Nov 2026
3 examples
Static method

Definition

Reflect.defineProperty(target, propertyKey, attributes) adds a new property to an object, or changes an existing one, using a descriptor that says how the property should behave: its value, and whether it is writable, enumerable and configurable.

It works like Object.defineProperty() with one big difference. When the change is not allowed, Object.defineProperty() throws an error, but Reflect.defineProperty() simply returns false. When it works, it returns true.

Remember
Reflect.defineProperty(target, key, descriptor)

changed or created  → true
not allowed         → false (no error)

Missing flags default to false:
  writable, enumerable, configurable

target must be an object, or TypeError

Syntax

Pass an object, the property name, and a descriptor object. Check the returned boolean.

JavaScript
const user = {};

const ok = Reflect.defineProperty(user, "id", {
  value: 7,
  enumerable: true
});

console.log(ok);          // true
console.log(user.id);     // 7
CallWhat it does
Reflect.defineProperty(obj, "id", { value: 7 })Create a property that is read-only, hidden from loops, and cannot be deleted.
Reflect.defineProperty(obj, "x", { value: 1, writable: true, enumerable: true, configurable: true })Create a normal property, like obj.x = 1.
Reflect.defineProperty(obj, "full", { get() { ... } })Define a getter instead of a plain value.
Object.defineProperty(obj, "id", { value: 7 })The older version. It returns the object and throws on failure.

A standard JavaScript static method (ES2015) of the Reflect object: call it as Reflect.defineProperty(). No import required. Siblings: Reflect.apply(), Reflect.construct(), Reflect.deleteProperty(), Reflect.get(), Reflect.getOwnPropertyDescriptor(), Reflect.getPrototypeOf(), Reflect.has(), Reflect.isExtensible(), Reflect.ownKeys(), Reflect.preventExtensions(), Reflect.set(), Reflect.setPrototypeOf().

Library declarations
JavaScript
// ECMAScript 2015 (ES6)
Reflect.defineProperty(target, propertyKey, attributes)

// target      : an object
// propertyKey : a string or a symbol
// attributes  : a descriptor object
// returns     : true or false
// throws      : TypeError if target is not an object

Parameters

ParameterDescription
targetRequired. The object to change. If it is not an object, a TypeError is thrown.
propertyKeyRequired. The name of the property: a string or a symbol.
attributesRequired. A descriptor object with some of value, writable, get, set, enumerable and configurable. You cannot mix value/writable with get/set.

Return Value

Return ValueDescription
trueThe property was created or changed.
falseThe change is not allowed, for example because the object is frozen or the property is not configurable.
TypeError (thrown)target is not an object, or attributes is not a valid descriptor.

JavaScript Examples

Example 1 — Define a Read-Only Property

Create a property with only a value, and see which flags JavaScript sets to false for you.

JavaScript
const user = {};

const ok = Reflect.defineProperty(user, "id", { value: 7 });
console.log("Defined: " + ok);
console.log("Value: " + user.id);

user.id = 99;
console.log("After user.id = 99: " + user.id);
console.log("Listed by Object.keys: " + Object.keys(user).length);
console.log("Writable flag: " + Reflect.getOwnPropertyDescriptor(user, "id").writable);
Try It Yourself

How It Works

  1. Create it. The descriptor only has a value, so the call returns true and user.id is 7.
  2. It is read-only. Because writable was left out, it is false. The assignment user.id = 99 is silently ignored.
  3. It is hidden. enumerable is also false, so Object.keys() does not list it.

Example 2 — False Instead of an Error

Try to add a property to a frozen object. Reflect returns false, while Object.defineProperty() throws.

JavaScript
const settings = Object.freeze({ theme: "dark" });

const ok = Reflect.defineProperty(settings, "size", { value: 12 });
console.log("Reflect: " + ok);

try {
  Object.defineProperty(settings, "size", { value: 12 });
  console.log("Object: worked");
} catch (err) {
  console.log("Object: " + err.name);
}

if (!ok) {
  console.log("Could not add size");
}
console.log("Has size: " + ("size" in settings));
Try It Yourself

How It Works

  1. A frozen object. Object.freeze() stops new properties from being added.
  2. Two reactions. Reflect.defineProperty() returns false, and Object.defineProperty() throws a TypeError. The catch block prints only the error type.
  3. Handle it with if. Because the result is a boolean, a plain if (!ok) is enough, with no try block needed.

Example 3 — Change an Existing Property

Make a property that cannot be configured, and try to change it afterwards.

JavaScript
const obj = {};

console.log("Create: " + Reflect.defineProperty(obj, "limit", { value: 10 }));
console.log("Change value: " + Reflect.defineProperty(obj, "limit", { value: 20 }));
console.log("Same value again: " + Reflect.defineProperty(obj, "limit", { value: 10 }));
console.log("Make writable: " + Reflect.defineProperty(obj, "limit", { writable: true }));
console.log("Final value: " + obj.limit);

const loose = { count: 1 };
console.log("Change a normal property: " + Reflect.defineProperty(loose, "count", { value: 5 }));
console.log("count is now: " + loose.count);
Try It Yourself

How It Works

  1. Locked after creation. The first call creates limit with writable and configurable set to false, so later changes are checked strictly.
  2. Only harmless changes pass. A new value, or turning writable back on, is refused with false. Repeating the same value is allowed and returns true.
  3. A normal property is flexible. count was created by assignment, so all its flags are true and the change works.

Browser & Runtime Support

Reflect.defineProperty() is part of ES2015 (ES6), together with the Reflect object. Every current browser and Node.js has it.

✓ ES2015 · Widely supported

Reflect.defineProperty()

Supported in Chrome 49+, Edge 12+, Firefox 42+, Safari 10+, Opera 36+ and Node.js 6+. Internet Explorer never got it.

ES2015 Standard since
Google Chrome 49+ · Desktop & Mobile
Full support
Microsoft Edge 12+ · Chromium and legacy
Full support
Mozilla Firefox 42+ · Desktop & Mobile
Full support
Apple Safari 10+ · macOS & iOS
Full support
Opera 36+ · Chromium based
Full support
Samsung Internet Recent versions · Android
Supported
Android WebView 49+ · Chromium based
Supported
Node.js 6+ · Server runtime
Supported
Deno Supported · JavaScript runtime
Supported
Bun Supported · JavaScript runtime
Supported
Internet Explorer No native support
Not supported
Reflect.defineProperty() Excellent

Bottom line: Safe to use in every current browser and in Node.js. The only thing to plan for is Internet Explorer, which has no Reflect at all.

Frequently Asked Questions

It adds a property to an object or changes an existing one, using a descriptor. It returns true if that worked and false if it was not allowed.
Object.defineProperty() returns the object and throws a TypeError when the change is not allowed. Reflect.defineProperty() returns true or false instead, so you can check the result with a simple if statement.
Flags that you leave out of the descriptor are false for a new property. enumerable is false by default, so the property is hidden from those loops. Add enumerable: true to show it.
Yes. Use get and set functions in the descriptor instead of value and writable, for example { get() { return 5; } }. You cannot use value and get in the same descriptor.
It returns false when the object is not extensible and the property is new, or when the existing property is not configurable and you try to change it in a way that is not allowed.

Next: Reflect.deleteProperty()

Learn how to remove a property from an object and find out whether it worked.

Reflect.deleteProperty() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

12 people found this page helpful