JavaScript Reference ยท Object
Object.defineProperty()
Reference for JavaScript Object.defineProperty(): create or change one property with a descriptor, make it read-only or hidden, or define a getter and setter.
Object.defineProperty() adds a property to an object, or changes an existing one, with full control over its attributes: whether the value can be changed (writable), whether it shows up in loops and Object.keys() (enumerable), and whether it can be deleted or redefined (configurable). It can also define an accessor property with a getter and a setter.
Plain assignment such as obj.x = 1 creates a property whose three attributes are all true. defineProperty() is the tool when you want something stricter, or when you need accessors that you build at run time.
Object.defineProperty(obj, "id", { value: 42, enumerable: true });
Try it
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Syntax
Object.defineProperty(obj, prop, descriptor)
| Name | Description |
|---|---|
obj |
The object to change. It must be an object (not a primitive). |
prop |
The property key: a string or a symbol. |
descriptor |
An object with value and writable (a data property) or get and set (an accessor property), plus enumerable and configurable. |
Return value: the same object that was passed in, now changed.
Exceptions: a TypeError if obj is not an object, if the descriptor mixes data and accessor fields (value with get), if get or set is not a function, or if you try to change a non-configurable property in a way that is not allowed. Redefinition of a frozen object's property also throws.
Usage notes
- Missing fields default to false or undefined when you create a new property: it will be non-writable, non-enumerable and non-configurable. When you modify an existing property, omitted fields keep their current values.
- Non-configurable is mostly one-way. After
configurable: falseyou can no longer delete the property or change its type, and you cannot make it enumerable or configurable again. A writable non-configurable data property can still change its value and can be made non-writable. - Assignments to read-only properties fail silently in sloppy mode and throw a
TypeErrorin strict mode and inside classes and modules. - Hidden does not mean private. Non-enumerable properties are skipped by
Object.keys(),for...inandJSON.stringify(), but can still be read directly and found withObject.getOwnPropertyNames(). Use#privateclass fields for real privacy. - Arrays: defining the property
lengthor an index follows array rules. It is rarely a good idea. - Performance: objects with many custom descriptors can be slower than plain objects in some engines. Use it where the guarantees matter.
- Several at once: use
Object.defineProperties(). To inspect the result useObject.getOwnPropertyDescriptor().
Browser support
Object.defineProperty() is available in every browser and JavaScript runtime.