---
title: "unload listener (bp/unload-listener)"
description: "An unload handler keeps the page out of the back/forward cache and often never fires on mobile (Lighthouse: page prevented back/forward cache restoration)."
url: http://localhost:4173/rules/bp/unload-listener
updated: 2026-11-11
---

# unload listener

> `bp/unload-listener` is a vetd rule. It flags: unload listener. It runs on every `check`, together with the TypeScript check.

| Fact | Value |
| --- | --- |
| Rule id | `bp/unload-listener` |
| Severity | warning |
| Group | Best practices |
| Tags | performance, lighthouse |

## Why it matters

An unload handler keeps the page out of the back/forward cache and often never fires on mobile (Lighthouse: page prevented back/forward cache restoration).

## How to fix it

Listen for pagehide or visibilitychange instead.

## Credit

Based on work by:

- [Google Chrome](https://developer.chrome.com/docs/lighthouse/overview): web.dev documents that unload handlers make pages ineligible for the back/forward cache.

## References

- [Back/forward cache](https://web.dev/articles/bfcache), web.dev
- [Window: unload event](https://developer.mozilla.org/en-US/docs/Web/API/Window/unload_event), MDN Web Docs

## Related rules

- [`bp/passive-listener`](http://localhost:4173/rules/bp/passive-listener.md)

## Get this text from vetd

MCP: call `explain` with `{ "diagnosticId": "bp/unload-listener" }`. CLI: `npx vetd explain bp/unload-listener`.

---

[All 92 rules](http://localhost:4173/rules.md) · Previous: [`bp/document-write`](http://localhost:4173/rules/bp/document-write.md) · Next: [`bp/passive-listener`](http://localhost:4173/rules/bp/passive-listener.md)