references/embedding.md
Embedding Globestudio
Generated by scripts/generate-skill-references.js from packages/react/src/index.tsx, packages/web-component/index.js, public/embed.js, src/components/embed-view.jsx, src/data/starter-react.js and src/utils/embed-snippets.js. Edits made here by hand are lost the next time it is generated.
Every embed is an iframe of https://globestudio.app/embed: the packages and the script loader only build that address. The globe renders on globestudio.app, so a page adds no three.js and no map data.
Contents
- Pick a method
- React: @globestudio/react
- Web component: @globestudio/element
- Plain iframe
- Script loader: embed.js
- /embed query parameters
- Design configs
- Light pages, transparency and size
- Check it renders
Pick a method
| The project | Use | |---|---| | React, Next.js, Remix, or Astro with React | @globestudio/react | | Vue, Svelte, Solid, Angular, Astro, or HTML with a bundler | @globestudio/element | | HTML with no build step | a plain iframe | | Webflow, Framer, WordPress, Notion, Squarespace | a plain iframe |
In the studio, the export dialog's Share tab writes the iframe, React and web component code for the design on screen.
React: @globestudio/react
Add @globestudio/react to the project, 0.1.1 or later: 0.1.0 dropped look whenever config was set, so a config of changes embedded over Default. <Globe> renders a plain iframe and keeps no state, so it renders on the server as is. In a Next.js server component use only serializable props; onLoad or a ref needs a client component.
With no project yet, offer the starter, a Vite and React app that already renders a <Globe>. Give the user https://globestudio.app/docs#react-component, which has the command that copies it and a StackBlitz link that opens it with nothing to install.
| Prop | Type | Default | Notes |
|---|---|---|---|
| look | LookId | "halftone" | Look preset id. LookId autocompletes every value Globestudio ships. |
| width | number \| string | "100%" | Width in CSS units. Numbers become pixels; use strings for %, vw, etc. |
| height | number \| string | 480 | Height in CSS units. |
| config | string | | The design's share config as a JSON string, JSON.stringify(design), not URL encoded: the component encodes it for the embed address. The app's Share tab writes one; from the MCP server's build_share_url, stringify the config it returns. It is layered over look when you set both, so a config that holds only changes keeps the rest of that look, and over Default when you set it alone. |
| theme | "light" \| "dark" | "dark" | The embed's palette. "light" switches the glow and grid to a palette for light pages and turns the white ink of Halftone, Wireframe, Toon and Threshold graphite. Halftone, Toon and Threshold paint a dark page of their own, where that ink is lost, so make them see-through in config too. Any other value keeps the dark one. |
| title | string | "Globestudio dotted globe" | Accessible title for the embedded iframe. Required for AT/SR. |
| className | string | | Forwarded className for the iframe. |
| style | CSSProperties | | Forwarded style for the iframe. Merged after the component's default border: 0 so callers can override anything. |
| loading | "lazy" \| "eager" | "lazy" | loading attribute. |
| source | string | | Optional source query param added to the embed URL. Use it to see where embeds are coming from in Vercel Analytics. Example: source="my-saas-landing". |
| onLoad | React.IframeHTMLAttributes<HTMLIFrameElement>["onLoad"] | | Fired when the iframe finishes loading. Forwarded. |
import { Globe } from "@globestudio/react";
const HERO_GLOBE = { v: 3, selection: "continent:Europe", dotColor: "#7dd3fc" };
export const Hero = () => (
<Globe look="crt" config={JSON.stringify(HERO_GLOBE)} height={520} title="Dotted globe of Europe" />
);
Web component: @globestudio/element
Add @globestudio/element to the project, 0.1.1 or later for the same reason, then import "@globestudio/element", which registers <globe-studio>. The import is safe on a server, but the element only draws in the browser, so under server rendering (Nuxt, SvelteKit, Astro) load it in client code. defineGlobeStudio(tag) registers it under another tag name.
| Attribute | Default |
|---|---|
| look | halftone |
| config | |
| theme | dark |
| source | |
| width | 100% |
| height | 480 |
| title | Globestudio dotted globe |
| loading | lazy |
<globe-studio look="crt" config='{"v":3,"selection":"continent:Europe","dotColor":"#7dd3fc"}' height="480" title="Dotted globe of Europe"></globe-studio>
With no build step, use a plain iframe instead. The element only builds that iframe, so the page gets the same globe.
Plain iframe
<iframe
src="https://globestudio.app/embed?look=crt&c=%7B%22v%22%3A3%2C%22selection%22%3A%22continent%3AEurope%22%2C%22dotColor%22%3A%22%237dd3fc%22%7D"
width="100%"
height="480"
style="border: 0;"
loading="lazy"
title="Dotted globe of Europe"
></iframe>
That address is what the packages build for look="crt" and the config above.
Script loader: embed.js
A page may already load embed.js, the script loader the docs give at https://globestudio.app/docs#script-tag-loader. It turns every element with data-globestudio into an iframe, also ones added later. The iframe fills the element; an element with no height of its own gets data-height pixels and follows the embed's resize messages. On such a page a globe is an element with these attributes; on a new page, write a plain iframe.
<div data-globestudio data-look="halftone" style="height: 480px"></div>
| Attribute | Sets | Default |
|---|---|---|
| data-look | look | |
| data-density | density | |
| data-dot-size | dotSize | |
| data-dot-color | dotColor | |
| data-world-fill | worldFill | |
| data-render-mode | renderMode | |
| data-selection | selection | |
| data-motion | motion | |
| data-tilt-x | tiltX | |
| data-tilt-y | tiltY | |
| data-auto-spin | autoSpin | |
| data-view | view | |
| data-static | static | |
| data-background | background | |
| data-transparent | transparent | |
| data-theme | theme | |
| data-config | c | |
| data-source | source | script-embed |
| data-title | the iframe title | Globestudio dotted globe |
| data-height | the host's height | 420 |
/embed query parameters
| Parameter | Takes | Default | Notes |
|---|---|---|---|
| look | a look id | default | The look the embed starts from. An unknown id shows Default. |
| background | hex, # optional, or transparent | | Page color behind the canvas. Without it the page takes the config's solid background, or else the look's. A color here keeps the page solid on a transparent look. |
| density | 1 to 90 | the look's; 40 with no look | Dot density. Without it or the config's density, the look's. A value of 0 or less, or not a number, keeps the look's. |
| dotSize | 0.1 to 25 | the look's; 10 with no look | Dot size. Without it or the config's dotSize, the look's. A value of 0 or less, or not a number, keeps the look's. |
| dotColor | hex, # optional | | Dot color. It renders darker than its hex, as it always has, so embeds made before stay the same. For the exact hex, set dotColor in a "v": 3 config. |
| worldFill | hex, # optional | | Land fill in solid maps, read like dotColor. |
| renderMode | dots or solid | | Dots or filled land. |
| selection | a region, as in the config | world | What the map shows. |
| motion | 0 to 100 | 35 | Read but has no effect yet. |
| tiltX | -45 to 45 | 0 | Camera tilt in degrees. |
| tiltY | -45 to 45 | 0 | Camera tilt in degrees. |
| autoSpin | 1 or 0 | 1 | Spin the globe. |
| view | globe or flat | | 3D globe or flat map. Wins over the config's viewMode; without either it is a globe. |
| static | 1 or 0 | 0 | 1 holds every animation still, for design tool canvases and screenshots. |
| source | text | embed | Analytics tag, sent back in the resize message. |
| transparent | 1 or 0 | the look's; 0 with no look | 1 makes the page see-through, to sit on the host page. A look's own transparency (Wireframe) needs no parameter; 0 turns it off. |
| theme | light | | Switches the glow and grid to a palette for light pages, and turns the white ink of Halftone, Wireframe, Toon and Threshold graphite. |
| plugin | figma | | The old Figma plugin's picker shell. Not for embeds. |
| c | a config, URL encoded | | Layered last, over the look and the parameters above. See Design configs. |
Design configs
config(the packages) andc(the address) take the design's JSON. Give the packages the JSON string,JSON.stringify(design); they encode it. In an address, encode it once withencodeURIComponent.- With a look, the config changes only the keys it names and the look keeps the rest, its density, dot size, background and transparency included. A
backgroundcolor in the address or the config keeps the page solid on a transparent look (Wireframe). Alone, the config goes over Default. - A config with
version, as the studio writes, is a whole design: insideshaderSettings,globeSettings,spaceSettingsandflowSettingsthe keys it leaves out get the app defaults, even with a look. - From the MCP server's
build_share_url, give a package the result'slookandJSON.stringifyof itsconfig, not thecof itsembed_url: that address carries the region, the colors and the density as their own parameters, so itsccan lack them. - The address must stay under 32,000 characters, so check the length of
https://globestudio.app/embed?c=plus the encoded config. A custom shape file or a long list of data points is what goes over.
Light pages, transparency and size
- On a light page, set
theme="light"on<Globe>or<globe-studio>,data-theme="light"for embed.js, ortheme=lightin a plain iframe. It switches the glow and grid to a palette for light pages. Onlylightis sent; any other value leaves the address as it was. - Make the design suit the page in its config too: a light
backgroundwith a darkdotColoron a look that keeps it (see Dot color in looks.md), or"backgroundStyle": "transparent"with dots that show on the page. - Halftone, Wireframe, Toon and Threshold paint white ink whatever
dotColorsays, so on a light page a transparent one all but disappears. The light theme turns their ink graphite; without it, give them a solid darkbackground. - Graphite ink shows only on a transparent or light background. Halftone, Toon and Threshold paint a dark page of their own, where it is lost, so with the light theme make them see-through as well:
"backgroundStyle": "transparent"in the config, ortransparent=1in a plain iframe. - In a plain iframe,
transparent=1orbackground=transparentlets the page show through. - Give the iframe or its container an explicit height; the packages default to 480 px. The embed posts
{ type: "globestudio-resize", height, source }to the parent page, which embed.js uses to size elements that have no height of their own. - Set
titleto say what the globe shows, for screen readers, and keeploading="lazy"for globes below the fold.
Check it renders
Rendering needs WebGL 2. Check by reading: the code, and the /embed address it builds, which the user can open in a browser to see the globe. If no one saw it render, say so. A blank globe usually means the browser has no WebGL 2. Thumbnails of each look, with no changes, are at https://globestudio.app/looks/<id>.png.