JavaScript Proxy

Beginner
9 min read
Updated: Nov 2026
3 examples
Object interception

Definition and Usage

A Proxy is a built-in JavaScript object that stands in front of another object. You use the Proxy instead of the original object, and every action on it (reading a property, writing a value, deleting, calling a function and more) first goes through code that you write. That code can log the action, check it, change it or block it.

You make a Proxy with new Proxy(target, handler). The target is the real object (or function). The handler is a plain object that holds traps: small methods such as get and set, each one catching one kind of action. A trap that you leave out simply lets the action pass to the target.

This page explains the idea. The Proxy Methods index links the full guides for Proxy.revocable() and for every trap, from handler.apply() to handler.setPrototypeOf().

Proxy is a constructor and cannot be copied for old browsers.

Always create it with new, as in new Proxy(target, handler). It works in every modern browser and in Node.js, but Internet Explorer does not have it, and no script can add it. Inside traps, use the matching Reflect method to do the normal action.

JavaScript Syntax

Create a Proxy with a target and a handler that has one trap:

JavaScript
const user = { name: "Ann", age: 30 };

const proxy = new Proxy(user, {
  get(target, key, receiver) {
    console.log("Reading " + String(key));
    return Reflect.get(target, key, receiver);
  }
});

console.log(proxy.name);
// Reading name
// Ann

Core Ideas

Ideas every Proxy tutorial in this series builds on:

IdeaExampleRemember
Proxynew Proxy(target, handler)An object that stands in front of another object and catches actions
Targetconst target = { name: "Ann" }The real object (or function) that the Proxy wraps
Handlerconst handler = { get() {} }A plain object that holds the traps
Trapget(target, key, receiver)A handler method that catches one kind of action
ReflectReflect.get(target, key, receiver)The usual way to do the normal action inside a trap
InvariantA frozen value must stay the sameA rule that traps cannot break, or JavaScript throws a TypeError
Revocable ProxyProxy.revocable(target, handler)A Proxy that you can switch off with revoke()

Proxy vs Getters and Setters

Before Proxy, the way to watch a property was Object.defineProperty() with a getter and setter. A Proxy can do much more:

TaskGetters and settersProxy
Watch a property that existsYes, one property at a timeYes, all properties with one trap
Watch a property added laterNoYes
Watch deleteNoYes, with deleteProperty
Watch in and Object.keys()NoYes, with has and ownKeys
Watch function callsNoYes, with apply and construct
Old browsersWorks in Internet Explorer 9 and upNot supported in Internet Explorer

Use a plain object when you only need to store data. Use getters and setters for one or two special properties. Use a Proxy when you want to watch or guard everything about an object, such as in validation, logging or default values. A Proxy is a little slower than a plain object, so do not wrap objects that your code uses in tight loops.

How a Proxy Works

Use the proxy, not the target

The trick only works when your code talks to the Proxy. The original object still works normally, and anyone who holds it directly bypasses the traps.

Each action has a trap

Reading calls get, writing calls set, the in operator calls has, delete calls deleteProperty, and a function call calls apply. There are 13 traps in total.

Missing traps pass through

If the handler has no trap for an action, the action goes straight to the target. An empty handler {} makes a Proxy that behaves exactly like the target.

Reflect does the normal thing

Inside a trap, Reflect has a method with the same name and arguments, such as Reflect.get() and Reflect.set(). Call it to perform the default action after your own code.

Traps cannot break the rules

JavaScript checks the answer of a trap against the target. For example, a trap cannot report a different value for a frozen property. If it does, a TypeError is thrown.

Real-Life Uses

A Proxy is a powerful tool. Common uses:

UseHow Proxy helps
ValidationCheck every value before it is stored, and throw a clear error for bad data, with the set trap.
Default valuesReturn a helpful value for a missing property instead of undefined, with the get trap.
Logging and debuggingRecord every read, write or function call to see how your data is used.
Protecting dataHide private names from Object.keys(), block deleting and make some properties read-only.
Temporary accessLend an object for a short time with Proxy.revocable() and take the access back later.

JavaScript Examples

Three short programs. Each one prints plain text that is the same every time you run it, and they all run in Node.js.

Example 1 — Watch Reads and Writes of an Object

Wrap an object so that every read and write leaves a note. The traps use Reflect to do the normal work.

JavaScript
const user = { name: "Ann", age: 30 };
const logs = [];

const watched = new Proxy(user, {
  get(target, key, receiver) {
    logs.push("get " + String(key));
    return Reflect.get(target, key, receiver);
  },
  set(target, key, value, receiver) {
    logs.push("set " + String(key));
    return Reflect.set(target, key, value, receiver);
  }
});

console.log("Name: " + watched.name);
watched.age = 31;
console.log("Age: " + watched.age);
console.log("Log: " + logs.join(", "));
console.log("Original age: " + user.age);
get() tutorial

How It Works

  1. Wrap the object. new Proxy(user, { get, set }) makes watched. Each trap saves a note in logs and then calls the matching Reflect method.
  2. Use the Proxy. Reading watched.name, writing watched.age and reading it again each run a trap, so the log has three notes in order.
  3. The target changed. Because the traps passed the work on, the original user object now has age 31.

Example 2 — Validate Values and Protect a Property

Reject a bad value with the set trap, and refuse to delete a property with the deleteProperty trap. The catch block prints the error type and message.

JavaScript
const settings = new Proxy({ volume: 5 }, {
  set(target, key, value, receiver) {
    if (key === "volume" && (typeof value !== "number" || value < 0 || value > 10)) {
      throw new RangeError("volume must be from 0 to 10");
    }
    return Reflect.set(target, key, value, receiver);
  },
  deleteProperty(target, key) {
    return key !== "volume" && Reflect.deleteProperty(target, key);
  }
});

settings.volume = 8;
console.log("Volume: " + settings.volume);

try {
  settings.volume = 50;
} catch (err) {
  console.log(err.name + ": " + err.message);
}

console.log("Delete volume: " + delete settings.volume);
console.log("Volume still: " + settings.volume);
set() tutorial

How It Works

  1. Check before storing. The set trap accepts numbers from 0 to 10 for volume. 8 is fine, so Reflect.set() stores it.
  2. Reject bad data. 50 is too big, so the trap throws a RangeError with a clear message, and the value stays 8.
  3. Protect a property. The deleteProperty trap returns false for volume, so delete gives false and the property stays.

Example 3 — Wrap a Function and Count Its Calls

A Proxy can also stand in front of a function. The apply trap runs on every call.

JavaScript
function square(n) {
  return n * n;
}

let calls = 0;
const counted = new Proxy(square, {
  apply(target, thisArg, args) {
    calls++;
    return Reflect.apply(target, thisArg, args);
  }
});

console.log(counted(3));
console.log(counted(4));
console.log("Calls: " + calls);
console.log("typeof: " + typeof counted);
apply() tutorial

How It Works

  1. A function as target. new Proxy(square, ...) wraps a function, so the Proxy is callable and typeof gives "function".
  2. Count, then call. The apply trap adds one to calls and runs the real function with Reflect.apply().
  3. Same results. The answers 9 and 16 are the normal results of square, and the counter shows 2 calls.

Proxy Methods

A Proxy has one static method and 13 traps. Each one has its own tutorial:

MethodWhat it does
Proxy.revocable()Create a Proxy that you can switch off later.
handler.apply()Catch a call of a function.
handler.construct()Catch the new keyword.
handler.defineProperty()Catch the definition of a property.
handler.deleteProperty()Catch the delete operator.
handler.get()Catch the reading of a property.
handler.getOwnPropertyDescriptor()Catch the request for a property descriptor.
handler.getPrototypeOf()Catch the request for the prototype, including instanceof.
handler.has()Catch the in operator.
handler.isExtensible()Catch the question whether new properties can be added.
handler.ownKeys()Catch the listing of keys.
handler.preventExtensions()Catch the request to lock an object.
handler.set()Catch the assignment of a value to a property.
handler.setPrototypeOf()Catch a change of the prototype.

Full list: Proxy Methods index.

Frequently Asked Questions

A Proxy is a built-in object that stands in front of another object (the target). Actions on the Proxy, such as reading, writing, deleting or calling, first go through traps that you write in a handler object, and the traps can log, check, change or block the action.
The target is the real object (or function) that the Proxy wraps. The handler is a plain object that holds the traps, such as get and set. A trap that is missing lets the action pass to the target.
A trap is a method of the handler that catches one kind of action. There are 13: apply, construct, defineProperty, deleteProperty, get, getOwnPropertyDescriptor, getPrototypeOf, has, isExtensible, ownKeys, preventExtensions, set and setPrototypeOf.
Reflect has a method with the same name and arguments as each trap. Calling it, for example Reflect.get(target, key, receiver), performs the normal action, so your trap can add its own code and still keep the default behaviour.
It works in every current browser (Chrome, Edge, Firefox, Safari and Opera) and in Node.js. It does not work in Internet Explorer, and it cannot be added to old browsers with a script.

Ready for the method guides?

Open the Proxy Methods index to learn every trap with syntax, runnable examples and FAQs.

Proxy Methods index →

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.

18 people found this page helpful