Hooks

The React SDK provides hooks for controlling avatars and accessing conversation state.

useAvatar

Main hook for avatar control.

import { useAvatar } from '@avatarium/react';
 
function ChatInput() {
  const { sendMessage, isConnected, isSpeaking } = useAvatar();
 
  return (
    <input
      disabled={!isConnected}
      placeholder={isSpeaking ? 'Avatar is speaking...' : 'Type a message'}
      onKeyPress={(e) => {
        if (e.key === 'Enter') {
          sendMessage(e.currentTarget.value);
          e.currentTarget.value = '';
        }
      }}
    />
  );
}

Return Values

Property	Type	Description
`sendMessage`	`(text: string) => Promise<void>`	Send a message to the avatar
`speak`	`(text: string) => Promise<void>`	Make avatar speak text directly
`stop`	`() => void`	Stop current speech
`connect`	`() => Promise<void>`	Connect to conversation
`disconnect`	`() => void`	Disconnect from conversation
`isConnected`	`boolean`	Whether connected
`isSpeaking`	`boolean`	Whether avatar is speaking
`conversationId`	`string \| null`	Current conversation ID

useMessages

Access the conversation history.

import { useMessages } from '@avatarium/react';
 
function MessageList() {
  const { messages, clearMessages } = useMessages();
 
  return (
    <div>
      {messages.map((msg, i) => (
        <div key={i} className={msg.role === 'user' ? 'user' : 'assistant'}>
          {msg.content}
        </div>
      ))}
      <button onClick={clearMessages}>Clear</button>
    </div>
  );
}

Return Values

Property	Type	Description
`messages`	`Message[]`	Array of messages
`clearMessages`	`() => void`	Clear message history
`lastMessage`	`Message \| null`	Most recent message

Message Type

interface Message {
  id: string;
  role: 'user' | 'assistant' | 'system';
  content: string;
  timestamp: Date;
  audioUrl?: string;
}

useAvatarStatus

Get detailed avatar status information.

import { useAvatarStatus } from '@avatarium/react';
 
function StatusIndicator() {
  const { status, latency, error } = useAvatarStatus();
 
  return (
    <div>
      <span className={`status-${status}`}>{status}</span>
      {latency && <span>{latency}ms</span>}
      {error && <span className="error">{error.message}</span>}
    </div>
  );
}

Return Values

Property	Type	Description
`status`	`'idle' \| 'connecting' \| 'connected' \| 'speaking' \| 'error'`	Current status
`latency`	`number \| null`	Last response latency in ms
`error`	`Error \| null`	Last error

Avatar Component Events