@avatarfirst/react

React bindings for the AvatarFirst SDK -- hooks, components, and pre-built overlay UIs.

Features

• AvatarProvider / AvatarAgent -- context providers syncing SDK state to React
• AvatarView -- streaming avatar display with fallback animations
• Hooks -- useAvatar(), useOverlay(), useAvatarEvent(), useAction()
• Overlay components -- CardOverlay, FormOverlay, TableOverlay, ProgressOverlay, ConfirmOverlay, ChatOverlay, InsightOverlay
• Animations -- motion variants and overlay animation presets
• Utilities -- cn() for className merging

Quickstart

import { createAvatarAgent, HeyGenAdapter, defineAction } from '@avatarfirst/core'
import { AvatarAgent, AvatarView, CardOverlay } from '@avatarfirst/react'

const agent = createAvatarAgent({
  engine: new HeyGenAdapter(),
  engineConfig: { serverUrl: 'http://localhost:3001' },
  actions: [
    defineAction({
      id: 'welcome',
      name: 'Welcome',
      trigger: { type: 'state', state: 'connected' },
      effect: {
        speak: 'Welcome!',
        overlay: {
          id: 'welcome',
          component: 'card',
          data: { title: 'Hello!' },
          position: 'bottom-center',
          animation: 'slide-up',
        },
      },
    }),
  ],
})

function App() {
  return (
    <AvatarAgent config={agent} overlayComponents={{ card: CardOverlay }}>
      <AvatarView size="fullscreen" />
    </AvatarAgent>
  )
}

Hooks

useAvatar()

Access avatar state and controls: state, isConnected, speak(), message(), start(), stop(), etc.

useOverlay(overlayId?)

Manage overlays: overlays, isVisible, show(), hide().

useAvatarEvent(event, handler)

Subscribe to engine events reactively.

useAction()

Trigger actions programmatically: trigger(actionId).

Overlay Components

| Component | Description | |-----------|-------------| | CardOverlay | Title, items list, action buttons | | FormOverlay | Dynamic form fields | | TableOverlay | Tabular data display | | ProgressOverlay | Step-by-step progress tracker | | ConfirmOverlay | Yes/No confirmation dialog | | ChatOverlay | Chat message interface | | InsightOverlay | AI insights with confidence scores |