React and Next.js

Orbz does not publish a React component. React and Next.js use the same <orb-z> element as every other framework.

React

Import the browser entry once from the client application entry or from a component module that runs in the browser:


import "@neongate-ai/orbz/react-types";
import "@neongate-ai/orbz/browser";
import { useState } from "react";
import type { OrbzState } from "@neongate-ai/orbz";
 
export function AssistantPresence() {
  const [state, setState] = useState<OrbzState>("idle");
 
  return (
    <div role="status" aria-live="polite">
      <orb-z state={state} preset="neongate" size="300px" />
      <span>Assistant is {state}</span>
      <button type="button" onClick={() => setState("listening")}>
        Listen
      </button>
    </div>
  );
}

Next.js App Router

Place registration and interactive state behind a client boundary. Server components can still render the client component normally.


"use client";
 
import "@neongate-ai/orbz/react-types";
import "@neongate-ai/orbz/browser";
 
export function AssistantPresence() {
  return <orb-z state="thinking" preset="neongate" size="300px" />;
}

The browser entry is SSR-safe: it does nothing when customElements is not available and defines the element when the client bundle executes.

Type the custom tag

Import the optional JSX type augmentation once in your React or Next.js TypeScript application:


import '@neongate-ai/orbz/react-types'

This adds TypeScript awareness for the native <orb-z> custom element. It does not create a React component, wrapper, runtime adapter, or React dependency in the Orbz runtime.

Assign structured properties

Voice engines, talk flows, and intelligence providers are JavaScript objects, not attributes. Assign them through a ref before the first scheduled talk run:


"use client";
 
import "@neongate-ai/orbz/react-types";
import "@neongate-ai/orbz/browser";
import { useCallback } from "react";
import type {
  OrbzElement,
  OrbzVoiceEnginePort
} from "@neongate-ai/orbz";
 
interface ProductPresenceProps {
  voiceEngine: OrbzVoiceEnginePort;
}
 
export function ProductPresence(props: ProductPresenceProps) {
  const setElement = useCallback(
    (element: HTMLElement | null) => {
      if (element) {
        (element as OrbzElement).voiceEngine = props.voiceEngine;
      }
    },
    [props.voiceEngine]
  );
 
  return <orb-z ref={setElement} state="idle" preset="neongate" />;
}

The repository’s React and Next.js examples use this native-element approach.