Troubleshooting

The tag renders, but no orb appears

The browser has probably not registered the custom element. Import the browser entry from client code:

import "@neongate-ai/orbz/browser";

Then inspect the registry:

console.log(customElements.get("orb-z"));

In React or Next.js, import Orbz from @neongate-ai/orbz/react and render it inside a Client Component. Do not import a source file from the repository.

The server says HTMLElement or customElements is undefined

Use a documented package entry point rather than evaluating browser-only application code on the server. Orbz’s root, browser, and React entries guard registration, but your own code must not call DOM globals during render.

Move DOM queries into the client bootstrap, an effect, or another framework mount hook. See SSR and hydration.

React reports that className, style, children, or ref is invalid

That is intentional. The React adapter is strict and only accepts documented Orbz controls. Internal styles live in a closed Shadow DOM; className and style are not theming escape hatches. Place layout wrappers, labels, and controls around Orbz, and customize the orb with preset, color*, size, and elevated.

TypeScript rejects preset and custom colors together

The props are a discriminated union. Choose one appearance mode:

<Orbz preset="neongate" />

or:

<Orbz colorPrimary="#7C3AED" colorSecondary="#22D3EE" />

Do not pass preset in the second form. Runtime JavaScript follows the same rule: a preset wins, custom colors are ignored, and Orbz logs a console error.

palette has no effect

palette is not a public attribute or property. Use preset:

<orb-z preset="magenta"></orb-z>

Available names are neongate, periwinkle, magenta, peach, mocha, and ivory.

A custom color does not appear

Remove the preset attribute before entering custom mode:

orb.removeAttribute("preset");
orb.setAttribute("color-primary", "#7C3AED");

Also verify that the value is a valid CSS color and that the attribute is one of the five supported names: color-primary, color-secondary, color-accent, color-highlight, or color-background.

paused="false" or elevated="false" is still enabled

These are HTML boolean attributes. Presence means true regardless of the string value. Remove the attribute:

orb.removeAttribute("paused");
orb.removeAttribute("elevated");

Or use the matching properties:

orb.paused = false;
orb.elevated = false;

In template frameworks, bind null or undefined when the attribute should be absent.

Motion is not playing

Check these controls in order:

1. Remove paused or set the paused property to false.
2. Inspect reduced-motion. always uses a static profile.
3. With system, check the operating-system reduced-motion preference.
4. Confirm speed is positive.
5. Confirm the element is connected and registered.

restart() rebuilds the current state’s animation, but it does not override a paused or reduced-motion policy.

The orb has the wrong state, speed, or preset

Unsupported runtime values normalize to safe defaults:

Use the exported TypeScript types and constants to catch unsupported values before runtime.

Vue warns that orb-z cannot be resolved

Configure Vue’s template compiler to treat the tag as a custom element:

vue({
  template: {
    compilerOptions: {
      isCustomElement: (tag) => tag === "orb-z",
    },
  },
})

Import @neongate-ai/orbz/browser from the Vue client entry as well.

Angular says orb-z is not a known element

Add CUSTOM_ELEMENTS_SCHEMA to the standalone component or NgModule that owns the template:

schemas: [CUSTOM_ELEMENTS_SCHEMA]

Then import the browser entry before bootstrapping the application.

Two microfrontends load different Orbz versions

The Custom Elements registry permits one definition per tag name. Orbz guards duplicate registration, so the first orb-z implementation registered on the page wins. Coordinate one exact version across remotes or let the shell own registration. See Orbz in microfrontends.

I cannot inspect or style the Shadow DOM

The shadow root is closed by design. Public CSS variables, parts, internal classes, and layer references are not supported. Use the strict documented attributes. If the public appearance controls cannot express a valid shared use case, open a focused proposal in GitHub Issues .

Still stuck?

When opening an issue, include:

• Orbz version and package entry point
• framework and framework version
• browser and operating system
• the smallest element or adapter props that reproduce the problem
• relevant build or console output

Open an Orbz issue  · View the npm package