globestudio

<div align="center">

# Globestudio

**Open-source dotted maps and animated 3D globes for designers, animators, and creative developers.**

<a href="https://globestudio.app"><img src="public/og/default.gif" alt="A dotted 3D globe rotating on the Globestudio share card" width="640" /></a>

Pick a country or the whole world, choose a look, change the dots and colors, and export PNG, SVG, WebM, MP4, or GIF. Built with React and Three.js.

[**globestudio.app**](https://globestudio.app/) · [All 21 looks](https://globestudio.app/gallery) · [Roadmap](ROADMAP.md) · [Discussions](https://github.com/alevizio/globestudio/discussions)

[![CI status](https://github.com/alevizio/globestudio/actions/workflows/ci.yml/badge.svg)](https://github.com/alevizio/globestudio/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-f6f2ea.svg)](LICENSE)
[![PRs welcome](https://img.shields.io/badge/PRs-welcome-9adfff.svg)](CONTRIBUTING.md)

</div>

---

## Why Globestudio?

Most open-source map tools are built for engineers: tile servers, geocoding,
GIS pipelines. Globestudio is for when the map is the picture, like a landing
page hero, a launch teaser, a scrollytelling explainer, or a deck slide that
needs a globe but not a database.

You work by eye with the studio's controls and export when it looks right.
The studio runs in your browser, and the code is MIT licensed.

## Features

- Maps of the world, a continent, a subregion, a country, or a US state.
- Flat map or 3D globe, drawn from the same dots, with a morph between the two.
- 12 dot shapes (Circle, Hexagon, Triangle, Pentagon, Square, Diamond, Star,
  Plus, Ring, Voxel, Particle Grid, ASCII glyphs), or upload your own SVG,
  PNG, JPEG or WebP.
- 21 looks: Default plus 20 shader looks (Halftone, Risograph, Newsprint,
  Aurora, Pixel, Bayer, Atkinson, Wireframe, CRT, Glitch, Bad TV, Bloom,
  Metal, Iridescent, Pencil, Corrupt, Toon, Threshold, Vapor, Sonar).
  Each look is a one-click preset that sets the background, density, dot
  size and globe chrome, applies at most one shader pass, and has its own
  URL at `/looks/:id`. You can change the shape, colors and region after
  picking one.
- Gradients and alpha on the dot color, land fill, and country stroke.
- Your own data: paste `lat,lng,value` or `country,value` lines to plot
  markers sized by value, optionally joined by arcs.
- Solid maps: filled land and stroked borders, river and city overlays,
  pasted GeoJSON lines and points, and 5 flat projections (Mercator, Equal
  Earth, Natural Earth, Winkel Tripel, Robinson). Dotted maps use Mercator.
- Animations: rotation, twinkle, size jitter, and network arcs. They stop
  under `prefers-reduced-motion`.
- Exports: PNG at 1x to 4x (the WebGL scene is re-rendered at that size); SVG
  with clean vector dots (6 effects are approximated with SVG filters, and
  the full shader look needs PNG or video); WebM, MP4 (where the browser can
  encode it), and GIF video; and a JSON config. Copy image puts the same PNG
  on the clipboard, ready to paste into Figma, Slides, Slack or Notion.
- Keyboard shortcuts: `S` shuffle, `[`/`]` cycle looks, `D` export, `R`
  reset, `G` toggle view, `H` toggle panel, `?` help.
- Accessibility: targets WCAG 2.2 AA and was self-audited. It works from the
  keyboard, a hidden DOM mirror describes the canvas state to screen readers,
  and reduced motion is respected. Known gaps are listed in
  [`ACCESSIBILITY.md`](ACCESSIBILITY.md).

## Quickstart

### Use it

The live tool runs entirely in your browser at
**[globestudio.app](https://globestudio.app/)**, and you don't need an
account.

### Run it locally

Requires Node 20.19+ (or 22.12+) and npm.

```bash
git clone https://github.com/alevizio/globestudio
cd globestudio
npm install
npm run dev
```

Open `http://127.0.0.1:5173/` and the studio loads. `VITE_TEASER=1 npm run dev`
shows the pre-launch waitlist teaser instead. Deploys set `VITE_TEASER=0`.

### Build it

```bash
npm run build      # → dist/
npm run preview    # serve dist/ locally
npm test -- --run  # the full Vitest suite
npm run test:e2e   # browser smoke + accessibility checks
```

## Embed it anywhere

### One-line script tag (recommended)

```html
<div data-globestudio data-look="halftone" data-density="50"
     style="width: 100%; height: 480px;"></div>
<script async src="https://globestudio.app/embed.js"></script>
```

About 3 KB gzipped, with no dependencies. It works in Webflow, Squarespace,
blog posts, and anywhere else you can add a script tag. Every embed param
except `theme` and `plugin` has a matching `data-*` attribute (`c` is
`data-config`). The script watches the
DOM with a MutationObserver and mounts elements added later, so SPAs and
dynamic content work too.

### Plain iframe

```html
<iframe
  src="https://globestudio.app/embed?look=halftone&density=70&autoSpin=1"
  width="100%"
  height="500"
  style="border:0"
  loading="lazy"
  title="Globestudio dotted globe"
></iframe>
```

The embed posts `{ type: "globestudio-resize", height }` through
`postMessage`; listen for it and resize the iframe to match. It needs WebGL 2.
Without it, the embed shows a short note and a link to open Globestudio in a
supported browser.

### React component or web component

```bash
npm install @globestudio/react     # <Globe look="aurora" />
npm install @globestudio/element   # <globe-studio look="aurora"></globe-studio>
```

Both wrap the same `/embed` route in an iframe, so every look works in both.
Setup and props: [`packages/react`](packages/react/) and
[`packages/web-component`](packages/web-component/).

The export dialog writes this code for the design on screen. Its Share tab
has an Embed code section with three options, iframe, React and Web
component, each with a Copy button. Open in CodePen, under the snippet,
opens the design in a new pen through the web component.

### Embed parameters

Every query param the `/embed` route reads, as parsed in
[`src/components/embed-view.jsx`](src/components/embed-view.jsx):

| Param | Type / range | Default | What it does |
|---|---|---|---|
| `look` | preset id (one of the 21 looks) | `default` | Base look preset. The params below override it |
| `selection` | `world` · `country:<ISO3>` · `continent:<Name>` · `subregion:<Name>` | `world` | What geography to draw |
| `density` | number, 1 to 90 | `40` | Dot grid density (invalid values fall back to the preset's) |
| `dotSize` | number, 0.1 to 25 | `10` | Dot size (invalid values fall back to the preset's) |
| `dotColor` | hex, `#` optional | preset's | Dot color |
| `worldFill` | hex, `#` optional | preset's | Land fill color |
| `renderMode` | `dots` · `solid` | preset's | Dot field or solid landmass |
| `motion` | number, 0 to 100 | `35` | Parsed but has no effect yet; reserved |
| `tiltX` | number, −45 to 45 | `0` | Camera tilt, degrees |
| `tiltY` | number, −45 to 45 | `0` | Camera tilt, degrees |
| `autoSpin` | `1` · `0` | `1` | Auto-rotate the globe |
| `static` | `1` · `0` | `0` | Freeze all motion (static previews in design-tool canvases) |
| `view` | `globe` · `flat` | the `c` config's view, else `globe` | 3D globe or flat map. Wins over the config's view |
| `background` | hex, `#` optional, or `transparent` | unset | Page background behind the canvas. Without it the page is painted only when the `c` config has a Solid background color. `transparent` is the same as `transparent=1` |
| `theme` | `dark` · `light` | `dark` | Globe chrome palette. `light` reads cleanly on light host pages |
| `transparent` | `1` · `0` | `0` | See-through document, composites onto the host page |
| `plugin` | `figma` | unset | The picker shell that versions 1 and 2 of the Figma plugin load: Look, Country or region, Density and View (Globe or Flat) pickers above an Insert button. Globe inserts a PNG; Flat inserts editable vectors, or a PNG past 2,500 dots or with the solid Bloom look. The current plugin loads the full studio at `/?plugin=figma` instead |
| `source` | string | `embed` | Analytics tag, echoed in resize `postMessage`s |
| `c` | URL-encoded config JSON | unset | Full share-config payload (what the Share dialog produces). Overrides the preset and the params above |

A JSON Schema for the `c` payload lives at
[`/schema/config.json`](public/schema/config.json).

For Figma there are two ways in. The export dialog's Figma tab copies the
design as vectors or as an image, ready to paste into a file, and it links
to the Community plugin, which runs the full studio inside Figma. The tab is
left out on a phone, where the tab row has no room for it.

[globestudio.app/integrations](https://globestudio.app/integrations) has
copy-paste setups for AI agents (MCP), Webflow, Framer, Figma, Notion,
WordPress (through a Custom HTML block), plain HTML, and React. In this repo:
[Figma plugin](figma-plugin/) ·
[WordPress block](wordpress-plugin/globestudio/) (manual install for now; it
is not on wordpress.org yet) ·
[Framer component](examples/framer-component/) ·
[embed snippet](examples/embed-snippet/)

Longer reads:
[How to make a dotted world map in 2026](docs/blog/2026-05-how-to-make-a-dotted-world-map.md) ·
[all articles](docs/blog/)

## Use it from AI tools (MCP)

Globestudio runs a hosted [Model Context Protocol](https://modelcontextprotocol.io)
server at **`https://globestudio.app/mcp`** (streamable HTTP, nothing to
install, no account). From Claude, Codex, Cursor or any other MCP client, an
agent can list and search looks, build share URLs, read a share link you paste
(`read_share_url`), and get embed snippets without leaving the chat.

| Client | Connect |
|---|---|
| Claude app (claude.ai, Desktop) | Customize, Connectors, then **+** and **Add custom connector**. Paste the URL. |
| Claude Code | `claude mcp add --transport http globestudio https://globestudio.app/mcp` |
| Codex | `codex mcp add globestudio --url https://globestudio.app/mcp` |
| Cursor | In `~/.cursor/mcp.json`: `{ "mcpServers": { "globestudio": { "url": "https://globe