View as Markdown Open in ChatGPT Open in Claude

Avatar

The component that displays your character and animates its mouth as it speaks.

<Avatar /> renders the avatar and keeps it in sync with the session — loading, connection status, and lip-sync are all handled for you. It reads everything it needs from the nearest AvatarProvider, so it takes no required props.

Basic usage

Place <Avatar /> anywhere inside AvatarProvider. Always give it a size — it fills its container, so without an explicit style size or a sized parent it won't be visible.

tsx

import { View } from "react-native";
import { Avatar } from "@avatarfactory/react-native";

export default function TalkingCharacter() {
  return (
    <View style={{ width: 320, height: 320 }}>
      <Avatar />
    </View>
  );
}

Always size <Avatar />. Because its root is flex: 1, inside an unsized parent it can collapse to zero height and render nothing. Pass style={{ width, height }} or wrap it in a sized View.

Props

Prop	Type	Default	Description
`style`Optional	`ViewStyle`	No default	Layout styles applied to the avatar's root view. Use to set width and height.
`loader`Optional	`React.ReactNode`	No default	Custom element shown while the avatar is resolving. Defaults to the SDK's animated connecting loader.
`errorFallback`Optional	`React.ReactNode`	No default	Custom element shown if the avatar fails to load at all. A session that ends after the avatar is painted keeps the avatar, so it never reaches this.
`captionStyle`Optional	`ViewStyle`	No default	Styling hook for the caption overlay. Shown when transcript.captions is on.
`statusBannerStyle`Optional	`ViewStyle`	No default	Styling hook for the connectivity banner. Shown when statusBanner.enabled is on.
`cameraPreviewCorner`Optional	`CameraPreviewCorner`	`"bottom-right"`	Which corner the camera self-view sits in. Only applies when perception.camera is enabled.
`hideCameraPreview`Optional	`boolean`	`false`	Hide the camera self-view. Discouraged — capture continues regardless (the view stays mounted, invisible), so all this removes is the user's ability to see that it is happening.

Whether an overlay exists at all is a provider decision (transcript, statusBanner, perception in the config); how it looks is an Avatar prop. Styling an overlay you never enabled does nothing.

There is no picture-in-picture layout and no fit override on React Native — both are web-only. React Native also ships no thinking indicator; read useAvatar().isResponseSlow and render your own.

There is no className prop on React Native. Style the container with the style prop (a ViewStyle object). To toggle the built-in start/stop buttons, set controls.enabled on <AvatarProvider> — not on <Avatar>.

What it renders

The Avatar component renders three layers inside a View:

Rive Native View

The animated character, rendered through @rive-app/react-native. Real-time lip-sync driven by character-level alignment data.

Connectivity Dot

A small indicator in the top-right showing session state. Green = connected, red = disconnected.

Control Buttons

Built-in start/stop buttons, shown only in call mode when controls.enabled = true on the provider.

Custom loader

Override the default loading indicator with your own element.

tsx

import { View, Text } from "react-native";

<View style={{ width: 320, height: 320 }}>
  <Avatar
    loader={
      <View style={{ flex: 1, alignItems: "center", justifyContent: "center" }}>
        <Text style={{ color: "rgba(255,255,255,0.4)" }}>Warming up…</Text>
      </View>
    }
  />
</View>

Custom error fallback

Show your own UI if the avatar fails to load (bad avatarId, no connectivity, etc.).

tsx

import { View, Text } from "react-native";

<View style={{ width: 320, height: 320 }}>
  <Avatar
    errorFallback={
      <View style={{ flex: 1, alignItems: "center", justifyContent: "center" }}>
        <Text style={{ color: "#ef4444" }}>Couldn't load the avatar.</Text>
      </View>
    }
  />
</View>

Sizing examples

Fixed size

tsx

<View style={{ width: 320, height: 320 }}>
  <Avatar />
</View>

Fill available space

tsx

<View style={{ flex: 1 }}>
  <Avatar style={{ flex: 1 }} />
</View>

Rounded with overflow clipping

tsx

<View style={{ width: 240, height: 240, borderRadius: 24, overflow: "hidden" }}>
  <Avatar />
</View>

AvatarProvider

useAvatar