avatar-container

A Web Component that displays the avatar video. The video track is automatically bound.

Usage

<avatar-container
  style="width: 400px; height: 400px;"
  volume="80"
  fit="cover"
></avatar-container>

Attributes

Attribute	Type	Default	Description
volume	number	100	Audio volume (0-100). Automatically calls SDK.setVolume() on change.
fit	string	"cover"	Video fit mode. "cover" | "contain" | "fill"

fit Options

Value	Description
"cover"	Fills the container while maintaining aspect ratio (overflow is clipped)
"contain"	Fits entirely within the container while maintaining aspect ratio (may have gaps)
"fill"	Stretches to fill the container, ignoring aspect ratio

Events

Event	Description
avatar-connected	Fired after the component is mounted to the DOM and the first render is complete. The SDK listens for this event to automatically bind the video track.

Video Auto-Binding

The video track is automatically connected in the following order:

1. When <avatar-container> is added to the DOM, it fires the avatar-connected event after the first render completes.
2. The SDK Core listens for this event and plays the Agora video track on the internal .avatar element.
3. Even if the video track is received first, it will be automatically bound when <avatar-container> is later added to the DOM.

Placement Order

For avatars with a welcome message configured, place <avatar-container> in the DOM before calling init(). The welcome message plays immediately upon connection, so if <avatar-container> is not yet in the DOM, audio may play without video.

Styling

Shadow DOM

Encapsulated with Shadow DOM, the style attribute only applies to the component's external layout such as size, position, and border. Internal video element styles cannot be changed.

<avatar-container
  style="
    width: 100%;
    max-width: 500px;
    aspect-ratio: 9/16;
    border-radius: 16px;
    overflow: hidden;
  "
></avatar-container>

Volume Control

// Method 1: Attribute change (internally calls SDK.setVolume())
document.querySelector('avatar-container').volume = 50;

// Method 2: Direct SDK API call
SDK.setVolume(50);

Both methods produce the same result. When the attribute changes, the component automatically calls SDK.setVolume().