JavaScript FinalizationRegistry unregister() Method

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

Definition

unregister() tells a FinalizationRegistry to stop watching objects. You give it the unregister token that you passed as the third argument of register(), and the registry removes every registration made with that token.

It returns true when at least one registration was removed and false when nothing matched. Use it when you have already cleaned something up yourself and do not want the cleanup callback to run for it later.

Remember
registry.unregister(token);

token    → the same object you gave as the
           3rd argument of register()
returns  → true   (something was removed)
           false  (nothing matched)

The token is not the target.
No token at register time = no way to cancel.

Syntax

Pass the same token you used in register(). The method returns a boolean.

JavaScript
registry.register(target, heldValue, unregisterToken);

const removed = registry.unregister(unregisterToken);
CallWhat it does
registry.unregister(token)Remove every registration that was made with token. Returns true if at least one was removed.
registry.unregister(target)Returns false when target was only the target and never the token. Only the third argument of register() counts.
if (registry.unregister(token)) { ... }Check the result when you want to know whether a registration really existed.

A standard JavaScript method (ES2021) on every FinalizationRegistry; no import required. Siblings: register().

Library declarations
JavaScript
// ECMAScript 2021
FinalizationRegistry.prototype.unregister(unregisterToken)

// returns true or false
// the token was given to: register(target, heldValue, unregisterToken)

Parameters

ParameterDescription
unregisterTokenRequired. The same object that you passed as the third argument of register(). A string, a number, null or undefined throws a TypeError, even if you never registered anything.

Return Value

Return ValueDescription
trueAt least one registration was found with this token and removed. Its cleanup callback will no longer be called.
falseNo registration matched. The token was never used, or it was already unregistered.
TypeError (thrown)The token is not an object.

JavaScript Examples

Example 1 — Cancel a Registration

Register one object with a token, then cancel it twice and read the result each time.

JavaScript
const registry = new FinalizationRegistry(() => {});

const file = { name: "report.txt" };

registry.register(file, "report.txt", file);

console.log("First unregister: " + registry.unregister(file));
console.log("Second unregister: " + registry.unregister(file));
console.log("Unknown token: " + registry.unregister({}));
Try It Yourself

How It Works

  1. Register with a token. The third argument of register() is file itself, so file is both the target and the token.
  2. First call. unregister(file) finds the registration and removes it, so it returns true.
  3. Nothing left to remove. The second call finds nothing, and so does a brand-new object that was never used as a token. Both return false.

Example 2 — Use the Token, Not the Target

The target and the token can be two different objects. Only the token cancels the registration.

JavaScript
const registry = new FinalizationRegistry(() => {});

const file = { name: "report.txt" };
const token = { owner: "upload-1" };

registry.register(file, "report.txt", token);

console.log("Using the target: " + registry.unregister(file));
console.log("Using the token: " + registry.unregister(token));

const notes = { name: "notes.txt" };
registry.register(notes, "notes.txt");

console.log("No token was given: " + registry.unregister(notes));
Try It Yourself

How It Works

  1. Target and token are different. file is the watched object and token is a separate object that acts as a key for cancelling.
  2. Only the token works. unregister(file) returns false because file was never used as a token. unregister(token) removes the registration and returns true.
  3. No token, no cancel. notes was registered without a third argument, so no value can cancel it, and unregister(notes) returns false.

Example 3 — Cancel a Group and Avoid the TypeError

Three registrations share one token, so one call removes all of them. Then four wrong values are tried as tokens.

JavaScript
const registry = new FinalizationRegistry(() => {});
const session = {};

registry.register({ name: "a.tmp" }, "a.tmp", session);
registry.register({ name: "b.tmp" }, "b.tmp", session);
registry.register({ name: "c.tmp" }, "c.tmp", session);

console.log("Remove the group: " + registry.unregister(session));
console.log("Remove it again: " + registry.unregister(session));

const wrongTokens = ["session", 42, null, undefined];

for (const wrong of wrongTokens) {
  try {
    registry.unregister(wrong);
  } catch (err) {
    console.log(String(wrong) + " -> " + err.name);
  }
}
Try It Yourself

How It Works

  1. One token, many registrations. All three objects were registered with the same session token. A single unregister(session) removes all three and returns true.
  2. Second call. The group is already gone, so the same call now returns false.
  3. Wrong types fail loudly. A string, a number, null and undefined are not objects, so each one throws a TypeError instead of returning false. The catch block prints the value and the error name.

Browser & Runtime Support

FinalizationRegistry is part of ES2021. Current versions of all major browsers and Node.js have it, including unregister().

✓ ES2021 · Widely supported

registry.unregister()

Supported in Chrome 84+, Edge 84+, Firefox 79+, Safari 14.1+ and Node.js 14.6+. Internet Explorer never got it.

ES2021 Standard since
Google Chrome 84+ · Desktop & Mobile
Full support
Microsoft Edge 84+ · Chromium
Full support
Mozilla Firefox 79+ · Desktop & Mobile
Full support
Apple Safari 14.1+ · macOS & iOS
Full support
Opera 70+ · Chromium based
Full support
Samsung Internet Recent versions · Android
Supported
Android WebView 84+ · Chromium based
Supported
Node.js 14.6+ · Server runtime
Supported
Deno Supported · JavaScript runtime
Supported
Bun Supported · JavaScript runtime
Supported
Internet Explorer No native support
Not supported
registry.unregister() Excellent

Bottom line: Safe to use in every current browser and in Node.js. The result of unregister() is always predictable, because it does not depend on garbage collection.

Frequently Asked Questions

It returns true when at least one registration was found for the token and removed, and false when nothing matched. If the token has the wrong type, it throws a TypeError instead of returning false.
Only the unregister token counts, which is the third argument of register(). If you never passed the target as that third argument, unregister(target) finds nothing. Pass the target as its own token, as in register(obj, "id", obj), when you want to cancel with it later.
Yes. After unregister() has removed a registration, the callback is no longer called for it, even when the object is collected later. That is why you call it when you have already done the cleanup by hand.
No, it is optional. If you do nothing, the registration simply stays until the object is collected. Call it only when you clean up yourself, for example in a close() method, and you do not want the callback to repeat the work.
No. The token must be an object (newer engines also accept a symbol that was not made with Symbol.for()). A string, number, null or undefined throws a TypeError, both in register() and in unregister().

Back to the index

You have seen both methods. Return to the index to review them side by side, or reread register() with a token in mind.

FinalizationRegistry 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.

11 people found this page helpful