avatar-container

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

Usage

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

Attributes

Attribute	Type	Default	Description
volume	number	100	Audio volume (0-100). Changing the property automatically calls SDK.setVolume(). An initial value set as an HTML attribute does not take effect — see "Volume Control" below.
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

An initial volume cannot be set via HTML attribute

A value set as an HTML attribute — <avatar-container volume="80"> — does not take effect. The component mounts before init() completes, so the SDK.setVolume() call at that point is ignored and is not re-applied once the connection is established.

Set the initial volume after the connection completes (CONNECTED_FINISH).

SDK.onStatus((status) => {
  if (status === 'CONNECTED_FINISH') {
    SDK.setVolume(80);
  }
});

// Method 1: Property 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. Changing the property makes the component call SDK.setVolume() automatically. It must be the JavaScript property, not the HTML attribute.