React SDK

The Streamoji React Avatar Creator SDK allows you to easily integrate a custom 3D avatar creation experience into your React application with just a few lines of code.

Installation

Install the package using your preferred package manager:

npm install @streamoji/react-avatar-creator
yarn add @streamoji/react-avatar-creator
pnpm add @streamoji/react-avatar-creator

Explore the complete sample React app on GitHub.

Basic Usage

The primary way to use the SDK is via the AvatarCreator component. You will need a temporary authToken generated on your server.

import React from 'react';
import { AvatarCreator, type AvatarExportedData } from '@streamoji/react-avatar-creator';

const MyAvatarCreator = () => {
  const handleAvatarExported = (data: AvatarExportedData) => {
    console.log('Avatar saved!', data.url);
    // data.url contains the link to the .glb 3D model
    // data.thumbnailUrl contains the link to the .png preview
  };

  return (
    <div style={{ width: '100%', height: '600px' }}>
      <AvatarCreator
        token="YOUR_TEMP_AUTH_TOKEN"
        config={{
          bodyType: 'Full',
          whiteLabelTitle: 'My Custom App',
          whiteLabelColor: '#6200EE',
          thumbnail: true
        }}
        onAvatarExported={handleAvatarExported}
        onReady={() => console.log('Creator is ready!')}
      />
    </div>
  );
};

export default MyAvatarCreator;

Reference

AvatarCreator Props

Prop	Type	Description
token *	string	A temporary authentication token for the session.
config	AvatarCreatorConfig	Configuration options for the creator UI and behavior.
onAvatarExported	function	Callback triggered when the user saves their avatar.
onReady	function	Callback triggered when the iframe is fully loaded.
onError	function	Callback triggered when an error occurs.
style	CSSProperties	Styles applied to the iframe container.

AvatarCreatorConfig

Property	Type	Default	Description
bodyType	`'Half'` \| `'Full'`	`'Full'`	Choose between a full-body or half-body avatar.
whiteLabelTitle	string	-	Custom title displayed in the creator header.
whiteLabelColor	string	-	Hex color code for the primary theme.
thumbnail	boolean	`true`	Whether to return a thumbnail URL on export.

AvatarExportedData

The data returned when an avatar is saved.

Property	Type	Description
url	string	The permanent URL to the `.glb` 3D model.
thumbnailUrl	string	The permanent URL to the `.png` thumbnail image (if enabled).

Thumbnail Generation: By default, the SDK generates a high-quality .png preview of the exported avatar. You can use this URL to display profile pictures or gallery previews without needing to render the full 3D model. To disable this behavior, set thumbnail: false in your configuration.

Advanced: Custom Integration

For complete control over the iframe or to build a custom wrapper, use the useAvatarCreator hook.

import { useAvatarCreator } from '@streamoji/react-avatar-creator';

const CustomCreator = ({ token }) => {
  const { url, isReady, setConfig } = useAvatarCreator({
    token,
    onEvent: (event) => {
      if (event.eventName === 'v1.avatar.exported') {
        console.log('Exported:', event.data);
      }
    }
  });

  return (
    <div className="relative">
      {!isReady && <LoadingSpinner />}
      <iframe src={url} title="Avatar Creator" className="w-full h-[600px] border-none" />
    </div>
  );
};

Security Best Practices

Server-Side Token Generation: Never generate tokens on the client-side using your clientSecret. Always perform the handshake on your secure backend and pass the resulting authToken to your frontend.

Short-Lived Tokens: Tokens are temporary and should be requested per session. They expire automatically to ensure maximum security.