useAvatar

Here’s all properties of useAvatar hook.

const { ... } = useAvatar({
    // Avatar State
    avatarId: 'af3f42c9-d1d7-4e14-bd81-bf2e05fd11a3',
    // Style Props
    scale: 1,
    style: {width: '400px', height: '400px'},
    ...
})

Width and height inside style props must be set to fix the size of the canvas.

Requirement

Avatar Id

avatarId

string

required

The identifier of the avatar.

Avatar Loaders

avatarLoaders

LoaderPlugin<any>[]

Show Loaders

ThreeJSPlugin

LoaderPlugin<any>

The loader of Threejs. Example: useAvatar({ avatarLoaders: [ThreeJSPlugin] }) // Default loader

Live2dPlugin

LoaderPlugin<any>

The loader of Live2D. Example: useAvatar({ avatarLoaders: [Live2dPlugin] })

RivePlugin

LoaderPlugin<any>

The loader of Rive. Example: useAvatar({ avatarLoaders: [RivePlugin] })

defaultAvatarLoaders

LoaderPlugin<any>[]

The loader of all provides (threejs, live2d, rive). Example: useAvatar({ avatarLoaders: defaultAvatarLoaders })

Scale

scale

number

The avatar size control.

range: [-5, 5]

Rotation

rotation

number

The avatar rotation control.

On Avatar Loaded

onAvatarLoaded

function

The callback function when the avatar is loaded.

Show Loaders

avatarId

string

After the avatar is loaded, the avatarId will be returned.

Example:

onAvatarLoaded: ({ avatarId }) => {
    console.log("avatarId", avatarId);
};

Function

Avatar Display

avatarDisplay

ReactNode

required

The avatar display component.

Show child attributes

const { avatarDisplay } = useAvatar({ ... })

return <>{avatarDisplay}</>

Connect Audio Context

connectAudioContext

function

required

The function is connecting the audio context. (Web Audio API)

Show child attributes

Examples:

const audioContextRef = useRef<AudioContext>(new AudioContext());

const [avatarInitialed, setAvatarInitialed] = useState();
const { ... } = useAvatar({
    onAvatarLoaded: ({ avatarId }) => {
        setAvatarInitialed(true);
    }
});

useEffect(() => {
    if (!avatarInitialed) return;
    connectAudioContext(audioContextRef.current);
}, [avatarInitialed]);

Connect Audio Element

connectAudioElement

function

The function is connecting the audio element. (HTML Audio Element)

Show child attributes

Examples:

const audioElementRef = useRef<HTMLAudioElement | null>(null);

const [avatarInitialed, setAvatarInitialed] = useState(false);

useEffect(() => {
    if (!avatarInitialed || !audioElementRef.current) return;
    connectAudioElement(audioElementRef.current);
}, [avatarInitialed]);

return (
    <>
        {avatarDisplay}
        <audio ref={audioElementRef} hidden/>
    </>
);

Connect Audio Node

connectAudioNode

function

The function is connecting the audio node. (Web Audio API)

Show child attributes

Examples:

const audioContextRef = useRef<AudioContext>(new AudioContext());
const [file, setFile] = useState<File | null>(null);

useEffect(()=>{
    const nf = await file!.arrayBuffer();

    const audioBuffer = await audioContextRef.current.decodeAudioData(nf);
    const bs = audioContextRef.current.createBufferSource();
    bs.buffer = audioBuffer;
    connectAudioNode(bs);
    bs.start();
},[file])

return (
    <>
        {avatarDisplay}
        <input type="file" onChange={(e) => setFile(e.target.files![0])} />
    </>
);

Available Triggers

Available in ThreeJSPlugin and RivePlugin.

availableTriggers

string[] | undefined

Get all available shape flow triggers. For example: [“happy”]

Example: const { availableTriggers } = useAvatar(...)

Trigger Event

Available in ThreeJSPlugin and RivePlugin.

triggerEvent

function

Trigger the avatar blendshape motion when the function clicked!

Show child attributes

Example:

const { triggerEvent } = useAvatar(...)
triggerEvent('happy')

Guides

Function

Use Cases

More

Requirement

Avatar Id

Avatar Loaders

Scale

Rotation

On Avatar Loaded

Function

Avatar Display

Connect Audio Context

Connect Audio Element

Connect Audio Node

Available Triggers

Trigger Event

Guides

Function

Use Cases

More

​Requirement

​Avatar Id

​Avatar Loaders

​Scale

​Rotation

​On Avatar Loaded

​Function

​Avatar Display

​Connect Audio Context

​Connect Audio Element

​Connect Audio Node

​Available Triggers

​Trigger Event

Requirement

Avatar Id

Avatar Loaders

Scale

Rotation

On Avatar Loaded

Function

Avatar Display

Connect Audio Context

Connect Audio Element

Connect Audio Node

Available Triggers

Trigger Event