onbeforeunload Event

Fires prior to a page being unloaded.

Syntax

Inline HTML<ELEMENT onbeforeunload = "handler" ... > All platforms
Event propertyobject.onbeforeunload = handlerJScript only
object.onbeforeunload = GetRef("handler")Visual Basic Scripting Edition (VBScript) 5.0 or later only
Named script <SCRIPT FOR = object EVENT = onbeforeunload> Internet Explorer only

Event Information

BubblesNo
CancelsYes
To invoke
  • Close the current browser window.
  • Navigate to another location by entering a new address or selecting a Favorite.
  • Click the Back, Forward, Refresh, or Home button.
  • Click on an anchor that refers the browser to another Web page.
  • Invoke the anchor.click method.
  • Invoke the document.write method.
  • Invoke the document.open method.
  • Invoke the document.close method.
  • Invoke the window.close method.
  • Invoke the window.open method, providing the possible value _self for the window name.
  • Invoke the window.navigate or NavigateAndFind method.
  • Invoke the location.replace method.
  • Invoke the location.reload method.
  • Specify a new value for the location.href property.
  • Submit a form to the address specified in the ACTION attribute via the INPUT type=submit control, or invoke the form.submit method.
Default action Signals that the page is about to be unloaded.

Event Object Properties

Although event handlers in the DHTML Object Model do not receive parameters directly, a handler can query the event object for the following event properties.

Available Properties

altKey Retrieves a value that indicates the state of the ALT key.
altLeft Retrieves a value that indicates the state of the left ALT key.
clientX Sets or retrieves the x-coordinate of the mouse pointer's position relative to the client area of the window, excluding window decorations and scroll bars.
clientY Sets or retrieves the y-coordinate of the mouse pointer's position relative to the client area of the window, excluding window decorations and scroll bars.
ctrlKey Sets or retrieves the state of the CTRL key.
ctrlLeft Sets or retrieves the state of the left CTRL key.
returnValue Sets or retrieves the return value from the event.
shiftKey Retrieves the state of the SHIFT key.
shiftLeft Retrieves the state of the left SHIFT key.
type Sets or retrieves the event name from the event object.

Remarks

When a string is assigned to the returnValue property of window.event, a dialog box appears that gives users the option to stay on the current page and retain the string that was assigned to it. The default statement that appears in the dialog box, "Are you sure you want to navigate away from this page? ... Press OK to continue, or Cancel to stay on the current page.", cannot be removed or altered.

Example

This example uses the onbeforeunload event to ask users whether they want to remain on the current page or navigate to a new URL. When the user clicks on the hyperlink or attempts to close the browser window, the onbeforeunload event fires on the body and a dialog box appears. If the user chooses 'OK', the page navigates to the new URL (www.microsoft.com) or closes the window; if the user chooses 'Cancel', the page remains the same.

<HTML>
<head>
<script>
function closeIt()
{
  return "Any string value here forces a dialog box to \n" + 
         "appear before closing the window.";
}
window.onbeforeunload = closeIt;
</script>
</head>
<body>
  <a href="http://www.microsoft.com">Click here to navigate to 
      www.microsoft.com</a>
</body>
</html>
This feature requires Microsoft Internet Explorer 4.0 or later. Click the following icon to install the latest version. Then reload this page to view the sample.

Standards Information

There is no public standard that applies to this event.

Applies To

BODY, FRAMESET, window, HTMLBodyElement Constructor, HTMLFrameSetElement Constructor, Window Constructor

See Also

Tags :


Community Content

weazybird
The onbeforeunload Event and the Anchor Tag

The onbeforeunload event is often used to warn a user that they have made changes to a web-based form if that user tries to leave the page without saving the changes. This is problematic for pages that use hyperlinks (the <a> anchor tag) to call client-side javascript, even when that code does not result in the user navigating away from the page.

For example, your page may offer a link that allows the user to manipulate content on the page through javascript and the DOM. Normally, you wouldn't want the user to be prompted because of the onbeforeunload event, but this is exactly what happens because you clicked a link and the IE browser believes you may be navigating away from the page.

You can prevent this from happening by using the onclick event of the anchor tag to prevent the onbeforeunload event from firing (set onbeforeunload = null) or setting a flag to allow the onbeforeunload event to continue without prompting the user.

Consider the following example where the method of setting a temporary flag is used. The flag is reset after a single use so you would need to call "NoPrompt()" from every link where onbeforeunload processing should be disabled.

<html>
<body>
<a href="javascript:alert('Hello World!');">Warning</a><br/>
<a onclick="NoPrompt();" href="javascript:alert('Hello World!');">No Warning</a>
<script>
// Allow the user to be warned by default.
var allowPrompt = true;
window.onbeforeunload = WarnUser;
 
function WarnUser()
{
   if(allowPrompt)
   {
      event.returnValue = "You have made changes. They will be lost if you continue.";
   }
   else
   {
      // Reset the flag to its default value.
      allowPrompt = true;
   }
}
 
function NoPrompt()
{
   allowPrompt = false;
}
</script>
</body>
</html>

Rim van Wersch
The onbeforeunload Event and the Anchor Tag revisited

Though weazybird's solution works, it is often an inconvenience to hunt down all links and add the onclick event. The same effect however can be achieved by defining a HTC behavior for links in your stylesheet that hooks the proper events. Instead of the onclick event, we found it useful to use the onMouseDown event to disable warnings and additionally hook the OnMouseOut event to re-enable them.

Tags :

george_5154
Dynamically generated iframes...
The onbeforeunload event, triggers on the main document if you create an iframe or if you use location.replace/assign on that iframe (which I think is an error, because the main document is not being reloaded), I consider this a major problem because the event object does not contain any member that tells you what caused the event to trigger, so you cannot handle it properly. On the other hand if you target a form to the same iframe the onbeforeunload event is not invoked (correct behavior). This behavior is clearly inconsistent.

It seams to me like nobody at Microsoft took the time make sure dynamically generated iframes would work fine, I have found lots of issues relating dynamically created iframes, and those issues affect only Microsoft products, all other browser work perfectly OK, so I hope someone is doing their job this time for the release of IE8.

Jorge Ojeda B
Prompt twice, and Error not specified when location.href is used

Besides the problem described by weazybird I'm getting this error: "Error not specified" ("Error no especificado") when the event handler's code contains location.href = www.myserver.com
The trick would be to add try/catch to catch the error in order to avoid showing the error to user.
Greeting,
Jorge


Westmatrix99
Refresh or close in IE8?

Tested code from weazybird...

In Internet Explorer 8 v8.0.6001.18702
Clicking Warning executes the code as set out
Page refresh executes the code WarnUser
Closing the window executes the code WarnUser

In Firefox 3v3.0.13
Clicking Warning executes the code alert(Hello World!)
Page refresh executes nothing
Closing the window executes nothing

This is built for IE, so force everyone to use IE, (...only joking)


Thomas Lee
Onbeforeunload gets into an infinite loop
We have a situation with IE8 only where onbeforeunload repeats itself after user presses "cancel".

The problem only happens if the content of the page is dynamically changed. But it doesn't happen as soon as the page is changed. Oonbeforeunload is turned off during dynamic changes.

When a user tries to browse away from the page, the onbeforeunload even kicks in as expected. The user clicks on "cancel" and the onbeforeunload pops right back up. It won't go away unless user presses OK which is too late if the user hasn't saved his changes.

This is definitly a bug in IE8. Other browsers (IE7, IE6, Firefox and Safari) work as expected. In our testing, IE8 showed this behavior about 90% of the time while we tested the same steps.


Page view tracker