JavaScript Proxy handler.deleteProperty() Method

Beginner
6 min read
Updated: Nov 2026
3 examples
Proxy trap

Definition

handler.deleteProperty(target, property) is a trap that runs when you delete a property of a Proxy with the delete operator, or with Reflect.deleteProperty(). Instead of removing the property straight away, JavaScript first runs your trap.

The trap returns true when the property is gone (or was never there) and false when it could not be deleted. Inside the trap you can protect properties, log what was removed, or clean up. To delete in the normal way, use Reflect.deleteProperty(target, property).

Remember
const handler = {
  deleteProperty(target, property) { ... }
};

target    → the original object
property  → the name (a string or a symbol)

return true  → the property is gone
return false → not deleted (strict mode: TypeError)

Syntax

Add a deleteProperty trap to the handler of a Proxy.

JavaScript
const user = new Proxy({ id: 1, name: "Ann" }, {
  deleteProperty(target, key) {
    if (key === "id") {
      return false;   // protect id
    }
    return Reflect.deleteProperty(target, key);
  }
});

console.log(delete user.name);   // true
console.log(delete user.id);     // false
CallWhat it does
delete proxy.aThe delete operator runs the trap.
delete proxy["a"]The same, with square brackets.
Reflect.deleteProperty(proxy, "a")The function-style version. It returns true or false.
proxy.a = undefinedDoes not run this trap. It changes the value and uses the set trap.

A standard JavaScript Proxy trap (ES2015). You write it inside the handler object that you pass to new Proxy(). JavaScript calls it for you. No import required. Siblings: Proxy.revocable(), handler.apply(), handler.construct(), handler.defineProperty(), handler.get(), handler.getOwnPropertyDescriptor(), handler.getPrototypeOf(), handler.has(), handler.isExtensible(), handler.ownKeys(), handler.preventExtensions(), handler.set(), handler.setPrototypeOf().

Library declarations
JavaScript
// ECMAScript 2015 (ES6)
handler.deleteProperty(target, property)

// target   : the original object
// property : a string or a symbol
// returns  : true or false

Parameters

ParameterDescription
targetThe original object that the Proxy wraps.
propertyThe name of the property that is being deleted: a string or a symbol.

Return Value

Return ValueDescription
trueThe property was deleted, or it did not exist.
falseThe property could not be deleted. In normal code delete then gives false. In strict mode it throws a TypeError.
TypeError (thrown)The trap broke a rule, for example by returning true for a non-configurable property of the target.

JavaScript Examples

Example 1 — Protect Properties from delete

Return false for names that must stay. Here, id and every name that starts with an underscore are protected.

JavaScript
const user = { id: 1, name: "Ann", _token: "abc" };

const safe = new Proxy(user, {
  deleteProperty(target, key) {
    if (key === "id" || (typeof key === "string" && key.startsWith("_"))) {
      return false;
    }
    return Reflect.deleteProperty(target, key);
  }
});

console.log("delete name: " + delete safe.name);
console.log("delete id: " + delete safe.id);
console.log("delete _token: " + delete safe._token);
console.log("Keys left: " + Object.keys(user).join(", "));
Try It Yourself

How It Works

  1. Check the name. The trap returns false for id and for any string that starts with "_". typeof key === "string" keeps symbols from breaking startsWith().
  2. Delete the rest. For other names, Reflect.deleteProperty() removes the property from the target and returns true.
  3. The target shows it. After the three deletes, only id and _token remain in the original object.

Example 2 — Strict Mode and Missing Properties

A refused delete is quiet in normal code, but throws in strict mode. Deleting something that does not exist counts as success. The catch block prints the error type only.

JavaScript
const safe = new Proxy({ id: 1 }, {
  deleteProperty(target, key) {
    if (key === "id") {
      return false;
    }
    return Reflect.deleteProperty(target, key);
  }
});

function remove(obj, key) {
  "use strict";
  return delete obj[key];
}

console.log("Normal delete: " + delete safe.id);

try {
  remove(safe, "id");
} catch (err) {
  console.log("Strict delete: " + err.name);
}

console.log("Reflect on id: " + Reflect.deleteProperty(safe, "id"));
console.log("Missing property: " + Reflect.deleteProperty(safe, "zzz"));
console.log("id is still " + safe.id);
Try It Yourself

How It Works

  1. Same refusal, different reactions. The trap returns false for id. A normal delete gives false. The same delete in a strict function throws a TypeError.
  2. Reflect gives a boolean. Reflect.deleteProperty() never throws for a refusal. It returns false, so you can react in your own way.
  3. Missing is fine. Deleting zzz, which does not exist, returns true, because afterwards the property is gone.

Example 3 — Keep a Trash List and Respect the Rules

Remember what was deleted, so it can be restored later. Then see that a trap cannot claim a frozen property was removed.

JavaScript
const trash = [];
const box = new Proxy({ a: 1, b: 2 }, {
  deleteProperty(target, key) {
    trash.push(key + "=" + target[key]);
    return Reflect.deleteProperty(target, key);
  }
});

delete box.a;
delete box.b;
console.log("Trash: " + trash.join(", "));
console.log("Keys left: " + Object.keys(box).length);

const fixed = {};
Object.defineProperty(fixed, "x", { value: 1 });
const liar = new Proxy(fixed, {
  deleteProperty() {
    return true;
  }
});

try {
  delete liar.x;
} catch (err) {
  console.log("Lying trap: " + err.name);
}
Try It Yourself

How It Works

  1. Look before you delete. The trap reads target[key] and saves it in trash, then deletes the property for real.
  2. Both deleted. After two deletes, the trash has both values and the object has no keys left.
  3. No lying. The property x is non-configurable, so it cannot be removed. A trap that returns true anyway makes JavaScript throw a TypeError.

Browser & Runtime Support

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

✓ ES2015 · Widely supported

handler.deleteProperty()

Supported in Chrome 49+, Edge 12+, Firefox 49+, 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 49+ · 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
handler.deleteProperty() Excellent

Bottom line: Safe to use in every current browser and in Node.js. A Proxy cannot be faked in old browsers, so do not use it where Internet Explorer must work.

Frequently Asked Questions

It is a method of the handler object that runs when a property of a Proxy is deleted with the delete operator or with Reflect.deleteProperty(). It receives the target and the property name, and returns true or false.
The property stays. In normal code the delete expression gives false. In strict mode it throws a TypeError. Reflect.deleteProperty() just returns false.
No. Setting a value uses the set trap (or defineProperty). Only the delete operator and Reflect.deleteProperty() run this trap.
true. Reflect.deleteProperty() returns true for a missing property, and that is the normal answer, because after the call the property is gone.
The target property is non-configurable, so it cannot be removed. JavaScript checks that the trap does not claim something that is not true. Return false for such a property, or use Reflect.deleteProperty() to get the right answer.

Next: handler.get()

Learn how a Proxy can watch and change every property read with the get trap.

handler.get() 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.

8 people found this page helpful