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.
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
Parameter
Description
unregisterToken
Required. 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 Value
Description
true
At least one registration was found with this token and removed. Its cleanup callback will no longer be called.
false
No 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.
Using the target: false
Using the token: true
No token was given: false
How It Works
Target and token are different.file is the watched object and token is a separate object that acts as a key for cancelling.
Only the token works.unregister(file) returns false because file was never used as a token. unregister(token) removes the registration and returns true.
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.
Remove the group: true
Remove it again: false
session -> TypeError
42 -> TypeError
null -> TypeError
undefined -> TypeError
How It Works
One token, many registrations. All three objects were registered with the same session token. A single unregister(session) removes all three and returns true.
Second call. The group is already gone, so the same call now returns false.
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.
Compatibility
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.
ES2021Standard since
Google Chrome84+ · Desktop & Mobile
Full support
Microsoft Edge84+ · Chromium
Full support
Mozilla Firefox79+ · Desktop & Mobile
Full support
Apple Safari14.1+ · macOS & iOS
Full support
Opera70+ · Chromium based
Full support
Samsung InternetRecent versions · Android
Supported
Android WebView84+ · Chromium based
Supported
Node.js14.6+ · Server runtime
Supported
DenoSupported · JavaScript runtime
Supported
BunSupported · JavaScript runtime
Supported
Internet ExplorerNo 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().