Raw WebGL in Flutter Web: Owning Your Own Canvas
Drive WebGL directly from a Flutter web app: getContext guards, GLSL programs, context-loss recovery, and a requestAnimationFrame loop bridged in with package:web inside an HtmlElementView.
Published on • November 11, 2026
AI Assistant

Flutter web already draws everything to a WebGL canvas, but that context belongs to CanvasKit and you never get to touch it. When you need real 3D or shader control of your own, you create a second canvas, own it, and drive it from Dart through JS interop. The canvas lives in an HtmlElementView; the rest of your app keeps behaving like ordinary Flutter.
What you are actually calling
WebGL brings an API based on OpenGL ES 2.0 to an HTML <canvas> without plug-ins. A WebGL program is control code written in JavaScript plus shader code (GLSL) that runs on the GPU: the control code compiles and links the shaders into a program, then issues the draw calls the GPU executes. You reach all of it through getContext():
function init(canvas) {
const gl = canvas.getContext('webgl');
if (gl === null) {
// No WebGL here — show a fallback instead of a blank box.
return null;
}
return gl;
}
The null guard is not optional: getContext() returns null when the context identifier is unsupported or when the canvas is already bound to a different context mode. Ask for 'webgl2' first, which maps to OpenGL ES 3.0, and fall back to 'webgl'. MDN’s browser-compat data puts WebGL2 in Chrome 56, Firefox 51, and Safari 15, so today the fallback mostly exists for ancient WebViews.
Register your own element factory
HtmlElementView embeds an HTML element in the widget hierarchy, and the embedded HTML is laid out like any other Flutter widget. Flutter web cannot guess how to build your canvas, so you register a factory for a view type using platformViewRegistry from dart:ui_web. That import only exists on the web target, so keep it behind a conditional import with a stub for the other platforms:
// web_gl_view.dart — web only
import 'dart:ui_web' as ui_web;
import 'package:web/web.dart' as web;
void registerWebGlView() {
ui_web.platformViewRegistry.registerViewFactory('webgl-view', (int viewId) {
final canvas = web.document.createElement('canvas') as web.HTMLCanvasElement;
canvas.width = 640;
canvas.height = 480;
canvas.style.width = '100%';
return canvas;
});
}
Place it like any other widget, then grab the context once the element exists in the DOM:
Widget build(BuildContext context) {
return const HtmlElementView(viewType: 'webgl-view');
}
web.WebGL2RenderingContext? acquireContext() {
final element = web.document.querySelector('canvas');
if (element is! web.HTMLCanvasElement) return null;
final ctx = element.getContext('webgl2');
if (ctx == null) return null; // no WebGL2 in this browser
return ctx as web.WebGL2RenderingContext;
}
Run your own render loop
Nothing repaints on its own: you draw when the browser is ready for a frame. Drive a requestAnimationFrame loop from Dart and keep the handle so you can stop it later:
int? _rafId;
void startLoop(void Function(double time) onFrame) {
late final web.FrameRequestCallback cb;
cb = ((double time) {
onFrame(time);
_rafId = web.window.requestAnimationFrame(cb);
}).toJS;
_rafId = web.window.requestAnimationFrame(cb);
}
void stopLoop() {
final id = _rafId;
if (id != null) web.window.cancelAnimationFrame(id);
_rafId = null;
}
Pointer input lands on the canvas element rather than on Flutter, so forward the events you care about into Dart callbacks and let the canvas keep the rest:
canvas.addEventListener('pointerdown', (web.Event event) {
final pointer = event as web.PointerEvent;
onPointerDown(pointer.offsetX.toDouble(), pointer.offsetY.toDouble());
}).toJS;
Survive context loss
Browsers take WebGL contexts away — GPU resets, driver crashes, aggressive background-tab eviction — and fire webglcontextlost on the canvas. Handle it or your scene vanishes permanently: restoration only happens if you cancel the default action:
canvas.addEventListener('webglcontextlost', (web.Event event) {
event.preventDefault(); // required, or webglcontextrestored never fires
running = false;
}).toJS;
canvas.addEventListener('webglcontextrestored', (web.Event event) {
uploadResources(gl); // buffers, textures and programs died with the context
running = true;
startLoop(drawFrame);
}).toJS;
Treat every buffer, texture, and program as owned by the context: on restore, rebuild them from your source data instead of assuming old handles still work.
When raw WebGL is the right tool
Reach for this when you want direct control of a 3D scene or a custom shader pipeline from Flutter web without a framework in front of you. When you do want a framework, three.js and Babylon.js sit on top of exactly this API — the companion three.js post covers that integration pattern. When all you need is one fragment effect over Flutter’s own output, FragmentProgram shaders are the lighter path, and CanvasKit’s context stays out of your hands either way.
Takeaway: Own a second canvas inside an HtmlElementView, guard getContext(), drive it with a requestAnimationFrame loop, and rebuild your GL resources on webglcontextrestored — that is everything a raw WebGL surface needs from Flutter web.