Cesium Syntax Viewer

CesiumJS Viewer Construction

Overview

Viewer is the standard entry point for a CesiumJS application. It wraps a CesiumWidget (canvas, Scene, Camera, Clock, render loop) and adds the UI widget set: animation control, timeline, base-layer picker, geocoder, home button, info box, and more.

Core principle: A CesiumJS application ALWAYS follows a fixed startup order. Set Ion.defaultAccessToken first, then construct the Viewer or CesiumWidget, then await async terrain and tileset factories, then add data and move the camera. Skipping or reordering the token step is the dominant cause of a blank globe.

When to Use This Skill

Use this skill when ANY of these apply:

• Creating a new CesiumJS application from scratch
• Choosing between Viewer and CesiumWidget
• A globe renders blank or black on first load
• The UI feels cluttered and widgets need to be turned off
• Tuning render quality through msaaSamples, contextOptions, or useBrowserRecommendedResolution
• A constructor throws because the container element is missing

Do NOT use this skill for camera movement (cesium-syntax-camera), entity or primitive content (cesium-syntax-entity, cesium-syntax-primitive), or bundler asset setup and CESIUM_BASE_URL (cesium-impl-build-deploy).

The Startup Order

ALWAYS run these steps in this exact order. NEVER construct the Viewer before the ion token line.

// 1. Set the ion token BEFORE constructing the Viewer.
Cesium.Ion.defaultAccessToken = "<your-ion-token>";

// 2. Construct the Viewer against an existing container element.
const viewer = new Cesium.Viewer("cesiumContainer");

// 3. await async terrain and tileset factories.
viewer.scene.setTerrain(Cesium.Terrain.fromWorldTerrain());

// 4. Add data and move the camera.
viewer.camera.flyTo({
  destination: Cesium.Cartesian3.fromDegrees(4.9, 52.37, 5000),
});

The Viewer constructor takes a container as the first argument: either a DOM element or the id string of an existing element. If the element does not exist, the constructor throws a DeveloperError.

Constructor Signature

const viewer = new Cesium.Viewer(container, options);

container is a DOM element or an element id string. options is an optional object. Every option has a default, so new Cesium.Viewer("id") alone produces a working globe.

Widget Toggles

Every widget toggle is a boolean. Set one to false to remove that piece of UI. Defaults verified against the API reference on 2026-05-20.

For a map with no Cesium UI chrome at all, set every toggle to false, or use CesiumWidget instead (see the decision tree below).

const viewer = new Cesium.Viewer("cesiumContainer", {
  animation: false,
  timeline: false,
  baseLayerPicker: false,
  geocoder: false,
  homeButton: false,
  navigationHelpButton: false,
  sceneModePicker: false,
  fullscreenButton: false,
});

Rendering Options

When requestRenderMode is true, the scene freezes until something requests a frame. ALWAYS call viewer.scene.requestRender() after any change the engine cannot detect on its own. Deep performance tuning belongs in cesium-core-performance.

contextOptions: WebGL Tuning

contextOptions passes raw flags to WebGL context creation. CesiumJS renders exclusively on WebGL2. NEVER configure a WebGPU path; no WebGPU backend exists in 1.124+.

const viewer = new Cesium.Viewer("cesiumContainer", {
  contextOptions: {
    requestWebgl2: true,
    webgl: {
      powerPreference: "high-performance",
      alpha: false,
    },
  },
});

powerPreference accepts "high-performance", "low-power", or "default". Set alpha: true only when the canvas must blend with HTML behind it.

Data Options

The baseLayer and terrain options expect async-aware helpers. ALWAYS feed terrain a Terrain instance such as Terrain.fromWorldTerrain(), and feed baseLayer an ImageryLayer from ImageryLayer.fromWorldImagery() or ImageryLayer.fromProviderAsync(...). NEVER pass a synchronously constructed provider that depends on a removed readyPromise. See cesium-core-versioning for the async-factory migration.

const viewer = new Cesium.Viewer("cesiumContainer", {
  terrain: Cesium.Terrain.fromWorldTerrain(),
  baseLayer: Cesium.ImageryLayer.fromWorldImagery({
    style: Cesium.IonWorldImageryStyle.AERIAL_WITH_LABELS,
  }),
});

Decision Tree: Viewer or CesiumWidget

digraph viewer_choice {
    rankdir=TB;
    node [shape=box, fontname="Helvetica"];
    start [label="Need a CesiumJS rendering surface"];
    q_ui [shape=diamond, label="Need any built-in Cesium UI widget\n(timeline, picker, geocoder, infoBox)?"];
    q_some [shape=diamond, label="Need a few widgets but not all?"];
    use_widget [label="Use CesiumWidget.\nNo toolbar, timeline, or inspector.\nExposes scene, camera, clock, canvas."];
    use_viewer_min [label="Use Viewer.\nDisable unwanted widgets with boolean toggles."];
    use_viewer [label="Use Viewer with default widgets."];

    start -> q_ui;
    q_ui -> q_some [label="yes"];
    q_ui -> use_widget [label="no"];
    q_some -> use_viewer_min [label="yes"];
    q_some -> use_viewer [label="no, need all"];
}

CesiumWidget is the foundational rendering component. It owns the canvas, Scene, Camera, Clock, and ScreenSpaceEventHandler, and runs the render loop, but has no UI chrome. It accepts the same rendering and data options as Viewer minus the widget toggles.

// Minimal UI-free rendering surface.
const widget = new Cesium.CesiumWidget("cesiumContainer", {
  scene3DOnly: true,
  msaaSamples: 4,
});
widget.scene; // same Scene API as viewer.scene

Teardown

A Viewer holds a WebGL context and GPU resources that the garbage collector NEVER reclaims on its own. ALWAYS call viewer.destroy() when removing a viewer, and check viewer.isDestroyed() before further use. Memory detail lives in cesium-core-memory.

Common Mistakes

Reference Files

• references/methods.md : the full constructor option catalog with types and defaults, key Viewer instance properties, and the CesiumWidget option set.
• references/examples.md : complete construction recipes for common application shapes.
• references/anti-patterns.md : each construction failure with symptom, root cause, and fix.

Related Skills

• cesium-core-architecture : the Viewer / CesiumWidget / Scene / Globe containment hierarchy and render loop.
• cesium-syntax-camera : moving the camera after construction.
• cesium-syntax-terrain : terrain provider async factories.
• cesium-syntax-imagery : imagery providers and layer ordering.
• cesium-core-versioning : the async-factory migration for providers.
• cesium-impl-build-deploy : CESIUM_BASE_URL and bundler asset setup.
• cesium-errors-rendering : diagnosing a blank or black globe.