JavaScript SDK

@avatarium/js provides the Avatarium class for embedding avatars in any JavaScript environment. For zero-install usage, the script tag widget is also available.

This SDK wraps an iframe – all 3D rendering, TTS, STT, and lip-sync run inside the hosted avatar page. Your app communicates with it via postMessage.

Core SDK (`@avatarium/js`)

Installation

npm install @avatarium/js

Quick Start

import { Avatarium } from '@avatarium/js';
 
const avatar = new Avatarium(document.getElementById('avatar'), {
  shortId: 'YOUR_SHORT_ID',
  mode: 'voice',
});
 
avatar.on('ready', (data) => console.log('Avatar ready:', data));
avatar.on('state', ({ state }) => console.log('State:', state));

Constructor

import { Avatarium, type AvatariumConfig } from '@avatarium/js';
 
const avatar = new Avatarium(container: HTMLElement, config: AvatariumConfig);

Parameter	Type	Required	Description
`container`	`HTMLElement`	✅	DOM element to mount the avatar iframe into
`config.shortId`	`string`	✅	Your avatar's Short ID from the dashboard
`config.mode`	`'voice' \| 'chat'`		Interaction mode (default: `'voice'`)
`config.host`	`string`		Override avatar host URL (default: `https://avatarium.ai`)

Methods

Method	Description
`avatar.on(event, handler)`	Subscribe to an event
`avatar.off(event, handler)`	Unsubscribe from an event
`avatar.destroy()`	Remove the iframe and clean up listeners

Events

// Avatar is fully loaded and ready for interaction
avatar.on('ready', (data: { avatar: string; thumbnail?: string }) => {
  console.log('Ready:', data);
});
 
// Avatar state changed
avatar.on('state', ({ state }: { state: 'idle' | 'listening' | 'thinking' | 'speaking' }) => {
  console.log('State:', state);
});
 
// Avatar started / stopped speaking
avatar.on('speaking:start', () => console.log('Speaking'));
avatar.on('speaking:end', () => console.log('Done speaking'));
 
// An error occurred
avatar.on('error', ({ message }: { message: string }) => {
  console.error('Error:', message);
});

Vanilla HTML Example

index.html

<div id="avatar" style="width: 400px; height: 600px;"></div>
 
<script type="module">
  import { Avatarium } from '@avatarium/js';
 
  const avatar = new Avatarium(document.getElementById('avatar'), {
    shortId: 'YOUR_SHORT_ID',
    mode: 'voice',
  });
 
  avatar.on('ready', (data) => console.log('Ready:', data));
  avatar.on('state', ({ state }) => {
    document.getElementById('status').textContent = state;
  });
</script>
 
<p>Status: <span id="status">loading...</span></p>

Vue Example

AvatarEmbed.vue

<script setup lang="ts">
import { ref, onMounted, onBeforeUnmount } from 'vue';
import { Avatarium } from '@avatarium/js';
 
const props = defineProps<{ shortId: string }>();
const containerRef = ref<HTMLElement | null>(null);
let instance: Avatarium | null = null;
 
onMounted(() => {
  if (!containerRef.value) return;
  instance = new Avatarium(containerRef.value, {
    shortId: props.shortId,
    mode: 'voice',
  });
  instance.on('ready', (data) => console.log('Ready:', data));
  instance.on('state', ({ state }) => console.log('State:', state));
});
 
onBeforeUnmount(() => instance?.destroy());
</script>
 
<template>
  <div ref="containerRef" style="width: 400px; height: 600px;" />
</template>

Svelte Example

AvatarEmbed.svelte

<script lang="ts">
  import { onMount, onDestroy } from 'svelte';
  import { Avatarium } from '@avatarium/js';
 
  export let shortId: string;
 
  let container: HTMLElement;
  let avatar: Avatarium;
 
  onMount(() => {
    avatar = new Avatarium(container, { shortId, mode: 'voice' });
    avatar.on('ready', (data) => console.log('Ready:', data));
  });
 
  onDestroy(() => avatar?.destroy());
</script>
 
<div bind:this={container} style="width: 400px; height: 600px;" />

TypeScript Types

import type { AvatariumConfig, AvatariumEvents } from '@avatarium/js';
 
const config: AvatariumConfig = {
  shortId: 'YOUR_SHORT_ID',
  mode: 'voice',
};

Widget (`@avatarium/widget`)

Drop a single script tag into any page – no build step required.

Usage

<script src="https://avatarium.ai/widget.js"></script>
<div id="avatarium-widget" data-avatar-id="YOUR_SHORT_ID" style="width: 400px; height: 600px;"></div>

Configuration

All configuration is via data-* attributes on the div:

Attribute	Default	Description
`data-avatar-id`	–	(required) Your avatar's Short ID
`data-width`	`100%`	Widget width
`data-height`	`600px`	Widget height

Programmatic Control

After the widget loads, a global window.AvatariumWidget object is available:

AvatariumWidget.destroy(); // Remove the widget

Finding Your Short ID

Go to dashboard.avatarium.ai (opens in a new tab)
Click on your avatar
Copy the Short ID (e.g., abc123)

Differences from `@avatarium/react`

Feature	`@avatarium/js`	`@avatarium/react`
Framework	Any	React 18+
API	Imperative (`new Avatarium(...)`)	Declarative (`<AvatariumEmbed>`)
Lifecycle	Manual (`destroy()`)	Automatic (unmount)
TypeScript	✅	✅
SSR	Manual (check for `document`)	Handled automatically

Both packages wrap the same iframe embed – choose based on your framework.

React Avatar Component