---

Why Globestudio?

Most open-source map tooling is built for engineers — tile servers, geocoding, GIS data pipelines. Globestudio is built for the other half of the stack: the landing-page hero shot, the launch teaser, the explainer scrollytell, the deck slide that needs a globe but not a database.

Think of it as a Shader Lab for maps and globes — a designer-first canvas with presets, effects, motion, and clean exports. Composable, web-native, and yours to remix.

Features

• 🌍 Maps for any scope — world, country, continent, subregion, US state
• 🔄 Flat ↔ 3D globe — same dot data, two views, smooth morph
• 🎨 12 dot shapes + custom upload — Circle · Hexagon · Triangle · Pentagon · Square · Diamond · Star · Plus · Ring · Voxel · Particle Grid · ASCII glyphs · your own SVG/PNG
• 🪄 21 shader looks: Halftone, Risograph, Newsprint, Aurora, Pixel, Bayer, Atkinson, Wireframe, CRT, Glitch, Bad TV, Bloom, Metal, Iridescent, Pencil, Corrupt, Toon, Threshold, Vapor, Topographic, plus the base Default. Each look applies at most one shader pass and works with any shape, color, or selection.
• 🌈 Gradients + alpha on dot color, land fill, and country stroke
• ✨ Live animations — rotation, twinkle, size jitter, network arcs, motion-aware (respects prefers-reduced-motion)
• 🎛️ 21 curated presets — every shader look is a one-click preset with matching backgrounds, density, dot size, and globe chrome. Shareable URLs at /looks/:id.
• 💾 Real exports: PNG at 1x to 4x (WebGL re-render); SVG with clean vector dots (6 effects approximated with SVG filters; the full shader look needs PNG or video); WebM, MP4, and GIF video; JSON config
• ⌨️ Full keyboard system — S shuffle, [/] cycle presets, D export, R reset, G toggle view, H toggle panel, ? help
• ♿ Accessibility: built to WCAG 2.2 AA and self-audited. Keyboard-first, a screen-reader proxy DOM for canvas state, reduced-motion support. Known gaps are listed in ACCESSIBILITY.md

Quickstart

Use it

The live tool runs entirely client-side:

→ globestudio.app

Pick a country, tweak the look, export.

Run it locally

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

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. To preview the pre-launch waitlist teaser instead, run VITE_TEASER=1 npm run dev; deploys set VITE_TEASER=0 (1 = teaser).

Build it

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

Globestudio ships several embed paths; pick whichever fits the tool:

One-line script tag (Recommended)

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

~3kb gzipped, zero dependencies, works in Webflow / Squarespace / blog posts / anywhere HTML is allowed. Every embed param has a matching data-* attribute. Watches the DOM for later-added elements via MutationObserver, so SPAs and dynamic content work too.

Plain iframe

<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>

Resize-aware via postMessage — listen for { type: "globestudio-resize", height } from the embed and resize the iframe to match. WebGL required; falls back to a still preview + a "how to enable WebGL" panel if the GL context can't be created.

React component or web component

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

Both are thin wrappers over the same /embed route, so every look works in both. Setup and props: packages/react and packages/web-component.

Embed parameters

The canonical parameter table. Every query param the /embed route honors, as parsed in src/components/embed-view.jsx:

A JSON Schema for the c payload lives at /schema/config.json.

Per-tool integration guides live at globestudio.app/integrations: copy-paste setups for Webflow, Framer, Figma, Notion, plain HTML, React, and WordPress, where Globestudio works via a Custom HTML embed. In this repo: Figma plugin · WordPress block (manual install; the wordpress.org listing comes after launch) · Framer component · embed snippet

Reading material: How to make a dotted world map in 2026 · All articles →

Use it from AI tools (MCP)

Globestudio runs a hosted Model Context Protocol server at https://globestudio.app/mcp (streamable HTTP, nothing to install, no account). Claude, Codex, Cursor and any MCP client can list looks, build share URLs, read a share link you paste (read_share_url) and grab embed snippets straight from a chat.

The same tools run locally over stdio: claude mcp add globestudio -- npx -y @globestudio/mcp.

No MCP client? The Share tab of the export dialog has Copy for AI: a prompt with your share link, its settings and what an agent can do with it, ready to paste into any chat. The same tab has the connect line for each client.

Full tool list and setup in packages/mcp/README.md.

What you can build with it

Runnable examples

The examples/ directory holds 9 reference projects — runnable HTML, drop-in components, and adaptation guides. Highlights:

• embed-snippet — the minimum-viable iframe pattern. Copy into Webflow, Framer, plain HTML, anywhere.
• hero-globe — full-bleed animated globe behind a landing-page hero.
• shader-presets-showcase — the shader presets in one auto-fit gallery, perfect for picking a look.

Share what you make in Show & Tell.

Documentation

How it compares

There's no shortage of map and globe tools — Globestudio doesn't try to replace any of them. It owns the aesthetic-asset shelf: stylized output that ships to a landing page hero, deck slide, OG card, or launch teaser. Different tools for different jobs:

What Globestudio gives up: GIS-accurate data overlays, large dataset analysis, real-time collaboration. If those are what you need, reach for Mapbox / Felt / Kepler — they're great at them.

Built on the shoulders of: globe.gl and COBE defined what a modern OSS 3D globe library looks like. dotted-map is the engine under the dot field. Stamen Maps was the spiritual ancestor of "maps as visual aesthetic."

Tech stack

Built with:

• React 19 + Vite for the app shell
• Three.js for the WebGL globe, instanced dot rendering, shader effects, network arcs
• dotted-map for the source dot field
• d3-geo + d3-geo-projection + topojson-client for the 5 flat projections of solid maps (Mercator, Equal Earth, Natural Earth, Winkel Tripel, Robinson; dotted maps use Mercator) and topology decoding
• world-countries + world-atlas + us-atlas for source geography
• satori + @resvg/resvg-js for the OG share card pipeline (JSX → SVG → PNG at build time)
• Pixelarticons by Gerrit Halfmann for the in-app icon set — 24×24 pixel-grid icons with currentColor fill so they theme cleanly
• Vitest + Testing Library + axe-core for tests and automated accessibility checks

No backend and no accounts. Privacy-respecting Vercel Analytics and Speed Insights honor Do Not Track, Global Privacy Control, and the local opt-out in /privacy; everything else renders in your browser.

Contributing

We want contributions. Code, presets, example projects, screenshots, docs rewrites — all of it counts.

The shortest path:

1. Build something cool with the live tool → drop it in Show & Tell
2. Found a bug? → Bug report
3. Made a preset you love? → Preset submission
4. Have an idea? → Ideas discussion

Full guide in CONTRIBUTING.md.

License

MIT. Use it, remix it, ship it. If you use it commercially or prominently we'd love to hear about it (no obligation, just curious).

The included geography data comes from world-atlas, us-atlas, and world-countries — all with permissive licenses. If you build on top of derived map data outside this repo, double-check the source attributions.

---