Installation

Package managers

CanvasGlobe 1.4.1 is published on npm under the stable latest tag.

npm

npm install canvas-globe

# pnpm
pnpm add canvas-globe

# Yarn
yarn add canvas-globe

# Bun
bun add canvas-globe

That is the whole dependency tree. The package has no runtime dependencies: country geometry and the time-zone table ship inside it.

import { createGlobe } from "canvas-globe";

Entry points

Import	What you get
canvas-globe	Everything: createGlobe, CanvasGlobe / GeoGlobe, helpers, themes, presets, scenes
canvas-globe/react	The <Globe> React component
canvas-globe/element	Registers the <geo-globe> custom element
canvas-globe/fx	54 composable animations and effect-authoring helpers
canvas-globe/fx/interaction	Pointer-driven effects without the complete effect catalogue
canvas-globe/charts	Nine animated geographic chart layers
canvas-globe/recipes	Six complete, reversible globe compositions
canvas-globe/controls	Search, timeline, threshold, and cross-filter bindings
canvas-globe/places	Optional offline search over 6,772 populated places
canvas-globe/data/world	Just the country geometry

React is an optional peer dependency. You only need it if you import /react.

Official framework packages

Choose the package that matches the terms developers already search for. Every package below uses the same CanvasGlobe renderer and commercial license.

Package	Use it for
react-canvas-globe	React and Next.js component
canvas-globe-vue	Vue 3 component
canvas-globe-angular	Angular standalone component
canvas-globe-svelte	Svelte and SvelteKit component
canvas-globe-web-component	Framework-independent custom element
3d-globe-map	Alternate discovery entry for the canonical JavaScript API
create-canvas-globe	Ready-to-run project starters

For example:

npm install canvas-globe-vue canvas-globe vue

Historical JSR release

CanvasGlobe 0.1.6 remains available as @swiftools/canvas-globe for projects that intentionally use the historical GPL-3.0-only release:

deno add jsr:@swiftools/[email protected]
npx jsr add @swiftools/[email protected]

import { createGlobe } from "jsr:@swiftools/[email protected]";

The JSR release predates the current proprietary 1.x line and does not contain later features or fixes. Use npm for the current maintained package and the React entry point so React remains your application's peer dependency.

Without a build step

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/canvas-globe.umd.js"></script>

Everything lands on a CanvasGlobe global. See No build step for the full walkthrough.

What it weighs

Piece	Gzipped
Country geometry (Natural Earth 1:110m)	~64 KB
Time-zone table	~7 KB
All the code	~43 KB
Core UMD bundle, including geography	~125 KB
Optional effects module	~25 KB
Optional charts module	~4 KB
Optional recipes module	~2 KB
Optional controls module	~2 KB
Optional places module	~94 KB

Most of the weight is map data, not code. If you bundle with a tree-shaking bundler and never touch a feature, its code drops out, but the geometry remains part of the globe renderer.

:::tip Bringing your own geometry If you already have GeoJSON, pass it as world and the bundled set is never referenced. Bundlers that support sideEffects: false will drop it. :::

Requirements

Any browser with <canvas> and ResizeObserver: Chrome, Edge, Firefox and Safari 13.1+. No polyfills.

The modules are safe to import during server-side rendering; nothing touches the DOM until you actually construct an instance.

TypeScript

Types ship with the package. There is nothing to install.

import { createGlobe, type Marker, type GeoGlobeOptions } from "canvas-globe";

const markers: Marker[] = [{ lat: 23.03, lon: 72.58, count: 12 }];