React e Next.js

Orbz não publica um componente React. React e Next.js usam o mesmo <orb-z> dos demais frameworks.

React

Importe a entrada do navegador uma vez no ponto de entrada cliente ou em um módulo de componente executado no navegador:


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} size="300px" />
      <span>Assistant is {state}</span>
      <button type="button" onClick={() => setState("listening")}>
        Listen
      </button>
    </div>
  );
}

Next.js App Router

Coloque o registro e o estado interativo atrás de uma fronteira cliente. Componentes de servidor podem renderizar o componente cliente normalmente.


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

A entrada é segura para SSR: não faz nada sem customElements e define o elemento quando o bundle cliente executa.

Tipagem da tag personalizada

Importe a extensão opcional de tipos JSX uma vez na aplicação TypeScript React ou Next.js:


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

Isso permite ao TypeScript reconhecer <orb-z>. Não cria componente React, wrapper, adaptador de runtime nem dependência React no runtime Orbz.

Atribua propriedades estruturadas

Mecanismos de voz, fluxos de conversa e provedores de inteligência são objetos JavaScript, não atributos. Atribua-os por uma ref antes da primeira execução agendada:


"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" />;
}

Os exemplos React e Next.js do repositório usam essa abordagem nativa.