Install
Orbit is two files: a stylesheet and a small runtime. Load both. The CSS does the geometry and the look; the runtime registers <o-arc> and <o-progress>, numbers the rings and keeps everything drawn as your layout changes.
From npm
npm install @zumer/orbit
Then, in the entry file of your app:
import '@zumer/orbit/style';
import '@zumer/orbit';
The package is safe to import during server rendering. Import it in the browser entry too, so it can register the elements and watch the page. It exports Orbit, OrbitArc, OrbitProgress and registerOrbit; registration happens on import.
From a CDN
Load it from unpkg. This always gets the latest release; add a version after the name (@zumer/orbit@2) if you want it to change only when you decide.
<link rel="stylesheet" href="https://unpkg.com/@zumer/orbit/dist/orbit.min.css">
<script defer src="https://unpkg.com/@zumer/orbit/dist/orbit.min.js"></script>
The script puts the API on window.Orbit. To load it as an ES module instead: import { Orbit } from 'https://unpkg.com/@zumer/orbit/dist/orbit.mjs'.
What is in the package
Everything lives in dist/. You can browse it on unpkg.
| File | Import as | What it is |
|---|---|---|
orbit.css, orbit.min.css | @zumer/orbit/style | The stylesheet: geometry, reset, default theme, theme-cyan, the color palette and dev-orbit. About 18 kB gzipped. |
orbit.mjs | @zumer/orbit (import) | The runtime as an ES module. |
orbit.js, orbit.min.js | @zumer/orbit (require) | The runtime as a classic script that sets window.Orbit. About 9 kB gzipped. |
orbit.d.ts, style.d.ts | TypeScript types for the API, the elements and the stylesheet import. | |
react.d.ts | @zumer/orbit/react | JSX types for <o-arc> and <o-progress>. Types only, no code. See React. |
custom-elements.json | @zumer/orbit/custom-elements.json | A Custom Elements Manifest for tools that read one. |
vscode.html-custom-data.json | @zumer/orbit/vscode.html-custom-data.json | Attribute completion for VS Code. |
To get that completion, add this to .vscode/settings.json:
{ "html.customData": ["./node_modules/@zumer/orbit/dist/vscode.html-custom-data.json"] }
Try it
A layout is a .bigbang with a .gravity-spot inside, and rings inside that. Put things on the rings: satellites with your content, arcs, progress, ticks. This one is a ring of eight satellites around a label. Edit it here, or press Copy page and save it as an index.html: it loads Orbit from unpkg and needs nothing else.
When something looks wrong
Orbit explains common mistakes in the browser console, in messages that start with [orbit]. Messages about structure appear when dev-orbit is on the .bigbang; the others always appear. Visual aids shows what dev-orbit draws.
| You see | Because | Fix |
|---|---|---|
| Nothing, and the console says has no size | The .bigbang is 0px wide or tall, usually in a parent that shrinks to fit. | Give the .bigbang or its parent a width. |
| A layout as big as the window | The .gravity-spot is not inside a .bigbang, so it measures the viewport. | Wrap it in a .bigbang. |
| An empty arc or ring | value is not a number, or max is not positive. | Fix the attribute; the console names it. |
| Content overlapping or off the ring | It sits directly in a ring instead of a .satellite. | Add dev-orbit to see where, then wrap it. |
| Curved text cut off | The text is longer than its arc. | Shorten it, widen --o-range, use range="auto", or fit-range. |
| Everything thin | Elements are one lane thick. | Raise --o-size-ratio on the ring or the system. |
| An arc that ignores clicks | Arcs are decorative by default. | Add interactive, and hit-width for a bigger target. |
| The console says Orbit.resize() has nothing to do here | The system already scales with its .bigbang. | Remove the call. See Runtime and resizing. |
Browser support
Orbit needs CSS sin(), cos() and container query units, which current versions of Chrome, Edge, Firefox and Safari all have. In a browser without trigonometric functions, each .bigbang turns into a red box that asks for an update.
Without JavaScript, a CSS fallback still places simple layouts: up to 24 rings and 60 children of each kind per ring. The fallback also needs :has() and :nth-child(… of …). <o-arc> and <o-progress> always need the runtime.
Next
- How Orbit thinks explains the model in one page.
- Build a knob puts it to work step by step.
- With a framework: React, Vue, Svelte, Angular, Astro.