Getting started

Orbz is a visual web component for AI voice experiences. Your application owns the microphone, model, audio playback, state machine, and business logic. Orbz turns those application states into one consistent visual presence.

The package is currently scoped as @neongate-ai/orbz, while the component itself is built on browser standards and does not depend on a framework.

Install

Choose the command for your package manager:


pnpm add @neongate-ai/orbz


npm install @neongate-ai/orbz


yarn add @neongate-ai/orbz

These docs describe Orbz 0.2.0. Until that version is published, the source workspace can exercise it through workspace:*; registry and CDN consumers should use the version that is actually available on npm .

Choose an entry point

Entry point	Use it when	Registration behavior
`@neongate-ai/orbz/browser`	You render the native element in Vanilla, Vue, Svelte, Angular, or another browser app	Defines `<orb-z>` automatically, once
`@neongate-ai/orbz/react`	You use React or a Next.js Client Component	Exposes the strict `<Orbz />` adapter and registers after mount
`@neongate-ai/orbz`	You need types, constants, utilities, or explicit registration	Exposes `defineOrbz()` without registering on import
`@neongate-ai/orbz/standalone`	You load Orbz as a browser module from a CDN	Self-contained browser bundle that defines `<orb-z>` automatically

All four entry points are safe to import in an environment without a DOM. The automatic entry points call a guarded, idempotent registration function, so a server import is a no-op and a browser never defines the tag twice.

Native quick start

Import the browser entry once in the client entry module:

main.ts


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

Then use the standards-based element in markup:

index.html


<div role="status" aria-live="polite">
  <orb-z
    state="listening"
    size="300px"
    speed="1"
    preset="neongate"
    reduced-motion="system"
    elevated
  ></orb-z>
  <span>Assistant is listening</span>
</div>

No stylesheet import is required. Orbz creates a closed Shadow DOM and owns its internal visual layers.

React quick start

Use the adapter when React should own the state:

assistant-orb.tsx


"use client";
 
import { Orbz, type OrbzState } from "@neongate-ai/orbz/react";
import { useState } from "react";
 
export function AssistantOrb() {
  const [state, setState] = useState<OrbzState>("idle");
 
  return (
    <section>
      <div role="status" aria-live="polite">
        <Orbz state={state} preset="neongate" size={300} elevated />
        <span>Assistant is {state}</span>
      </div>
 
      <button type="button" onClick={() => setState("listening")}>
        Start listening
      </button>
    </section>
  );
}

The React adapter deliberately accepts only Orbz configuration props. It does not expose className, style, children, or a forwarded ref.

Connect your assistant

Map the lifecycle that already exists in your application to the five visual states:

Application phase	Orbz state
Waiting for input	`idle`
Capturing the user	`listening`
Waiting for a model or tool	`thinking`
Playing a response	`speaking`
Disabled or dormant	`asleep`


type AssistantPhase =
  | "ready"
  | "recording"
  | "processing"
  | "playing"
  | "disabled";
 
const stateByPhase = {
  ready: "idle",
  recording: "listening",
  processing: "thinking",
  playing: "speaking",
  disabled: "asleep",
} as const;

Animation is supporting feedback, not the only status indicator. Keep readable state text in the surrounding interface and use a live region when changes need to be announced.

Next steps

Follow the native web component guide for attributes, properties, and imperative methods.
Follow the React and Next.js guide for the typed adapter.
Review the complete API reference.
Explore the source and full framework examples on GitHub .