@globestudio/react

Drop-in React component for embedding Globestudio dotted globes and maps. Zero deps, SSR-friendly, autocomplete on every preset.

Install

npm install @globestudio/react
# or pnpm add @globestudio/react
# or yarn add @globestudio/react

Use

import { Globe } from "@globestudio/react";

export default function Page() {
  return (
    <section>
      <h1>Worldwide coverage</h1>
      <Globe look="aurora" width={800} height={600} />
    </section>
  );
}

That's it. The component is a styled <iframe> over globestudio.app/embed, so the heavy lift (Three.js, shaders, country data) runs on the embed origin — your bundle stays a couple hundred bytes.

Props

| Prop | Type | Default | Notes | |---|---|---|---| | look | LookId | "halftone" | Autocomplete on every shipped preset | | width | number \| string | "100%" | Numbers → pixels | | height | number \| string | 480 | Numbers → pixels | | config | string | — | Pre-built share-URL payload — overrides look | | title | string | "Globestudio dotted globe" | A11y label | | className | string | — | Forwarded | | style | CSSProperties | — | Merged after border: 0 | | loading | "lazy" \| "eager" | "lazy" | Off-screen embeds defer WebGL until scrolled near | | source | string | — | Tag for analytics attribution | | onLoad | (e) => void | — | Forwarded |

Helpers

import { globestudio } from "@globestudio/react";

const embed = globestudio.embedUrl({ look: "vapor" });
//          → "https://globestudio.app/embed?look=vapor"

const thumb = globestudio.thumbnailUrl("halftone");
//          → "https://globestudio.app/looks/halftone.png"

const share = globestudio.shareUrl("eyJsb29rIjoidmFwb3IifQ");
//          → "https://globestudio.app/?c=eyJsb29rIjoidmFwb3IifQ"

Use these when you need the URL but not the iframe (e.g. Next.js <Image src>, server-rendered markup, OG metadata).

SSR

The component is just JSX — renders the iframe HTML on the server, hydrates on the client without re-mounting (no client-only state, no useEffect).

// app/page.tsx (Next.js App Router)
import { Globe } from "@globestudio/react";

export default function Page() {
  return <Globe look="risograph" />;
}

Sizing patterns

// Fill container
<Globe look="halftone" />  {/* width="100%", height=480 default */}

// Square in a card
<div style={{ width: 320, aspectRatio: "1 / 1" }}>
  <Globe look="aurora" width="100%" height="100%" />
</div>

// Background hero
<section style={{ position: "relative", height: 520 }}>
  <Globe
    look="vapor"
    width="100%"
    height="100%"
    style={{ position: "absolute", inset: 0 }}
  />
  <div style={{ position: "relative", padding: 64 }}>
    <h1>Hero content over the globe</h1>
  </div>
</section>

Why a package and not a copy-paste snippet?

The snippet on globestudio.app/integrations is what most people start with. The package adds:

• TypeScript autocomplete on look — no typos shipping to prod
• Versioning — pin to a tested version, upgrade deliberately
• One-line install in SaaS templates that ship via npm
• globestudio.* helpers for URL building outside the iframe context

The total surface area is one component and one helper object. Stays tiny on purpose.

License

MIT — see LICENSE.