Skip to content
Tutorials Center
My learning

Topics

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.

JavaScript
Object.defineProperty(obj, "id", { value: 42, enumerable: true });

Try it

JS A read-only, hidden property

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS An accessor property

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Syntax

JavaScript
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: false you 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 TypeError in strict mode and inside classes and modules.
  • Hidden does not mean private. Non-enumerable properties are skipped by Object.keys(), for...in and JSON.stringify(), but can still be read directly and found with Object.getOwnPropertyNames(). Use #private class fields for real privacy.
  • Arrays: defining the property length or 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 use Object.getOwnPropertyDescriptor().

Browser support

Object.defineProperty() is available in every browser and JavaScript runtime.