@bible-strong/avatar-react

React 19 renderer for a validated Bible Strong AvatarDefinition. React and React DOM 19 are peer dependencies; @bible-strong/avatar-core is installed as a normal dependency.

Install

pnpm add @bible-strong/avatar-react react react-dom

Import the package stylesheet once in the application entry point:

import { Avatar, type AvatarController } from '@bible-strong/avatar-react'
import type { AvatarDefinition } from '@bible-strong/avatar-core'
import '@bible-strong/avatar-react/styles.css'
import { useRef } from 'react'

export function Assistant({ definition }: { definition: AvatarDefinition }) {
  const avatar = useRef<AvatarController>(null)
  return (
    <>
      <Avatar ref={avatar} definition={definition} defaultAnimation="idle" />
      <button onClick={() => avatar.current?.play('happy')}>Play happy</button>
      <button onClick={() => avatar.current?.setExpression('neutral')}>Neutral</button>
    </>
  )
}

For a reusable component tied to one JSON definition, use createAvatar. It validates the definition once and, when the JSON is statically typed, narrows animation, defaultAnimation, expression and defaultExpression to the semantic keys present in that definition:

import { createAvatar } from '@bible-strong/avatar-react'
import avatarJson from './strobi.avatar.json'

const StrobiAvatar = createAvatar(avatarJson)

export function Strobi() {
  return <StrobiAvatar defaultAnimation="idle" />
}

Definitions fetched at runtime are validated by the same factory, but their keys are necessarily checked at runtime rather than inferred by TypeScript.

play and setExpression return { ok: true } or a typed error with one of unknown_animation, unknown_expression or controlled_by_props. pause freezes the exact timeline position, calling play with the paused key resumes it, and stop returns an uncontrolled avatar to neutral.

Props reference

Avatar exposes typed props for the definition, playback state and presentation. AnimationKey and ExpressionKey are semantic string keys from the supplied definition.

Definition and playback

animation and expression are two alternative sources of truth. Passing both throws an error; the component never silently overrides one with the other. A controlled target takes priority over an uncontrolled default when they are intentionally mixed.

Presentation

Playback callbacks

Unknown keys passed through animation, expression, defaultAnimation or defaultExpression are reported to onError. Without an error handler, the component writes the typed runtime error to the developer console instead of failing silently.

Imperative API

Pass a ref to receive an AvatarController. Use it when buttons, events or another imperative source need to drive an uncontrolled avatar:

play and setExpression return { ok: true } or { ok: false, error }. Errors include unknown_animation, unknown_expression and controlled_by_props. When animation or expression is controlled by props, use those props to change the target; imperative target commands cannot replace the parent value.

The definition is validated once per immutable object reference and revalidated/reinitialized when that reference changes.

Styling hooks

The stylesheet exposes .bs-avatar and .bs-avatar__svg. Consumer className and style are applied to the outer wrapper.

The public component never exposes Studio IDs or document types. The package follows Semantic Versioning. While it remains below 1.0.0, breaking API changes increment the minor version and fixes increment the patch version.