HTML oncontextlost Event Attribute

If this site has been useful, we’d love your support! Consider buying us a coffee to keep things going strong!

Description

The oncontextlost event attribute is used to specify JavaScript code to execute when a WebGL rendering context is lost. This event is primarily relevant for <canvas> elements that are using WebGL (Web Graphics Library) to render 3D graphics.

When a WebGL context is lost, it means the browser has temporarily or permanently invalidated the graphics context - this can happen due to reasons like GPU resets, graphics driver issues, or the system reclaiming GPU resources. Handling this event allows developers to respond appropriately, such as by cleaning up resources, notifying users, or attempting to restore the context.

Event Trigger

Element: <canvas> (with a WebGL context)
Event Type: webglcontextlost
JavaScript Property: canvas.oncontextlost = function(event) { ... };

Syntax

HTML Attribute Syntax:

<canvas id="myCanvas" width="500" height="500" oncontextlost="handleContextLost(event)"></canvas>

JavaScript Event Listener Syntax:

const canvas = document.getElementById("myCanvas");

canvas.addEventListener("webglcontextlost", function(event) {
    event.preventDefault(); // Prevent default behavior
    console.log("WebGL context lost!");
}, false);

Important: You usually need to call event.preventDefault() inside the handler to prevent the browser from taking its default action, which may be to discard the WebGL context permanently.

Event Object Properties

When the event is triggered, the event object provides the following:

event.type → "webglcontextlost"
event.target → The <canvas> element whose context is lost
event.preventDefault() → Method to prevent the browser’s default behavior

Common Use Case

A typical scenario is when a WebGL application needs to restore the rendering context after a loss:

canvas.addEventListener("webglcontextlost", function(event) {
    event.preventDefault();
    alert("WebGL context lost. Attempting to restore...");
}, false);

canvas.addEventListener("webglcontextrestored", function() {
    console.log("WebGL context restored!");
    // Reinitialize textures, buffers, and shaders here
});

oncontextlost → Handles the loss of the context
oncontextrestored → Handles the restoration of the context

Key Points

Browser Support: Most modern browsers that support WebGL also support this event.
Not a Common Event: It’s specific to WebGL; regular HTML elements won’t trigger this event.
Prevention Needed: Always call event.preventDefault() if you plan to restore the context; otherwise, the context will be lost permanently.
Alternative Handling: You can attach handlers via JavaScript (addEventListener) instead of inline HTML attributes.

Example in HTML + JavaScript

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>WebGL Context Lost Example</title>
</head>
<body>
<canvas id="glCanvas" width="400" height="400" 
        oncontextlost="alert('WebGL context lost!'); event.preventDefault();"></canvas>

<script>
const canvas = document.getElementById("glCanvas");
const gl = canvas.getContext("webgl");

canvas.addEventListener("webglcontextlost", function(event) {
    event.preventDefault();
    console.log("Caught WebGL context lost via JS!");
});
</script>
</body>
</html>

Syntax

<canvas id="myCanvas" oncontextlost="script(event)"></canvas>

Values

scriptThe name of the script to use when the event has been triggered.

Example

HTML

<!DOCTYPE html>

<html lang="en">

<head>

<meta charset="UTF-8">

<title>WebGL Context Lost Example</title>

</head>

<body>



<h2>WebGL Canvas Example</h2>



<canvas id="glCanvas" width="200" height="200" style="border:1px solid black;"></canvas>

<br>

<button id="loseContextBtn">Simulate Context Loss</button>



<script>

const canvas = document.getElementById("glCanvas");

const gl = canvas.getContext("webgl");



// Clear canvas with a blue color

gl.clearColor(0.2, 0.6, 0.9, 1.0);

gl.clear(gl.COLOR_BUFFER_BIT);



// Handle context lost

canvas.addEventListener("webglcontextlost", function(event) {

    event.preventDefault(); // Prevent permanent loss

    alert("WebGL context lost!");

});



// Handle context restored

canvas.addEventListener("webglcontextrestored", function() {

    alert("WebGL context restored!");

    // Reinitialize WebGL content

    gl.clearColor(0.2, 0.6, 0.9, 1.0);

    gl.clear(gl.COLOR_BUFFER_BIT);

});



// Button to simulate context loss

document.getElementById("loseContextBtn").addEventListener("click", function() {

    const ext = gl.getExtension("WEBGL_lose_context");

    if(ext) {

        ext.loseContext(); // Simulate context lost

    } else {

        alert("WEBGL_lose_context extension not supported in this browser.");

    }

});

</script>



</body>

</html>

Result

Editor

Browser Support

The following information will show you the current browser support for the HTML oncontextlost event attribute. Hover over a browser icon to see the version that first introduced support for this HTML event attribute.