Chevron Down
Table of Contents
Chevron DownGetting Started
Chevron DownAPI Reference


Provides functions to create and initialize a WebGL context, and to check for presence of WebGL and extensions.

  • Provides the createGLContext method which can create WebGLContexts both in browsers and under Node.js.

Note that the use of these functions is NOT required to use the remaining functions and classes in

You could e.g. manually create a WebGLContext by using canvas.getContext, or use a context created by another WebGL library. In fact, is explicitly designed to work with any WebGL context, and in contrast to some other approaches, maintains no "hidden state" that might complicate composing your code with other WebGL based modules.


Create a WebGL context, autocreating a canvas

import {createGLContext} from '';
const gl = createGLContext(); // Prefers WebGL2 but falls back to WebGL1

Create a WebGL2 context, failing gracefully if WebGL2 is not supported.

import {createGLContext} from '';
const gl = createGLContext({
  webgl1: false,
  throwOnError: false
if (!gl) {
  console.error('WebGL2 not supported');

Create a WebGL context in an existing canvas, setting WebGL context attributes

import {createGLContext} from '';
const gl = createGLContext({
  canvas: 'my-canvas-id',
  stencil: true,       // Default render target gets a stencil buffer of at least 8 bits.
  antialias: false,    // Turn of antialiasing
  premultipliedAlpha: false, // turn off pre-multiplied alpha.
  preserveDrawingBuffer: true, // Default render target buffers will not be automatically cleared

Create a headless WebGL context (under Node.js). headless-gl must be installed (npm install gl).

import {createGLContext} from '';
const gl = createGLContext({width: 100, height: 100});



Creates and returns a WebGL context, both in browsers and in Node.js.

const gl = createGLContext(options);
  • options (Object) - key/value pairs containing context creation options
ParameterBrowser defaultHeadless defaultDescription
webgl2trueN/AIf true, will attempt to create a WebGL2 context. Will silently fall back to WebGL1 contexts unless webgl1 is set to false.
webgl1truetrueIf true, will attempt to create a WebGL1 context. The webgl2 flag has higher priority.
throwOnErrortruetrueNormally the context will throw an error on failure. If false, it will log to console instead.
break[]N/AInsert a break point (debugger) if one of the listed gl functions is called.
manageStatetruetrueInstrument the context to enable state caching and withParameter calls. Leave on unless you have special reasons not to.
debugfalseN/AWebGL API calls will be logged to the console and WebGL errors will generate JavaScript exceptions. Note the enabling debug mode has a signficant performance impact.
canvasnullN/AA string containing the id of an existing HTML element or a DOMElement instance. If null or not provided, a new canvas will be created.
alphatrueN/ADefault render target has an alpha buffer.
depthtrueN/ADefault render target has a depth buffer of at least 16 bits.
stencilfalseN/ADefault render target has a stencil buffer of at least 8 bits.
antialiastrueN/ABoolean that indicates whether or not to perform anti-aliasing.
premultipliedAlphatrueN/ABoolean that indicates that the page compositor will assume the drawing buffer contains colors with pre-multiplied alpha.
preserveDrawingBufferfalseN/ADefault render target buffers will not be automatically cleared and will preserve their values until cleared or overwritten
failIfMajorPerformanceCaveatfalseN/ADo not create if the system performance is low.
widthN/A800width (number) of the headless "virtual screen" render target. Ignored for browser contexts
heightN/A600height (number) of the headless "virtual screen" render target. Ignored for browser contexts


  • In browser environments, contexts are created via HTMLCanvasElement.getContext. If the webgl2 option is set, this function will first try webgl2 and then experimental-webgl2, before falling back to webgl1.
  • In Node.js environments, the context is created using headless-gl. In this case width and height options must be supplied as there is no canvas element to use as reference.