ElementAPI

Every render function receives two arguments: the resolved props from your schema, and an ElementApi object. The api object is your element's window into the host environment.

render(props, api) {
  // api gives you everything the host knows about this element's context
}

api.element

The raw Chalk node for this element. Contains the authored content and parsed attributes before schema resolution.

• api.element.body — the text content written inside { } in Chalk
• api.element.detail — the content written inside [ ]
• api.element.attributes — the raw attribute list (prefer using a schema instead)
• api.element.animation — the parsed cue config, if the element is wrapped in cue{} or cue.morph{}

render(props, api) {
  const label = api.element.body ?? 'Default label'
  return <p>{label}</p>
}

A short callout element that reads body content and an optional colour attribute:

defineElement({
  kind: 'callout',
  category: 'inline',
  schema: {
    colour: { id: 'colour', type: { kind: 'color', default: 'blue' } },
  },
  render(props, api) {
    return (
      <div className={`callout callout--${props.colour}`}>
        {api.element.body}
      </div>
    )
  },
})

api.animation

The current scene animation state. Use this to drive time-based or cut-based behaviour without reading from the cue hooks directly.

interface AnimationState {
  isPaused: boolean
  isFinished: boolean
  loopEnabled: boolean
  currentPartitionIndex: number | null
  restartCounter: number
  hasAnimations: boolean
  hasTimeAnimations: boolean
}

• isPaused — true while the student has paused playback
• currentPartitionIndex — the active scroll partition (1-based), or null in time-based scenes
• restartCounter — increments each time the scene is restarted; watch it to reset stateful simulations

The animation hooks (useFade, useDraw, useMorph) read from this state internally — you rarely need to access it directly unless you are building custom animation behaviour.

api.storage

Per-element key/value storage. State saved here persists across page reloads and sessions, scoped to this element instance and the current user.

interface KeyValueStorage {
  get<T>(key: string): Promise<T | null>
  set<T>(key: string, value: T): Promise<void>
  delete(key: string): Promise<void>
}

See the Storage page for full patterns and guidance.

api.params

Current parameter values for slider-driven attributes. If an educator uses a parameter element in the same scene, its current value is available here.

render(props, api) {
    // An attribute declared as kind: 'paramNumber' resolves via api.params
    // You can also read raw param values directly:
    const n = api.params['n'] ?? 10
    return <Chart dataPoints={n} />
}

A circle whose radius is driven by a slider the educator places in the scene:

defineElement({
  kind: 'param-circle',
  category: 'inline',
  schema: {
    r: { id: 'r', type: { kind: 'paramNumber', default: 40 } },
    colour: { id: 'colour', type: { kind: 'color', default: 'teal' } },
  },
  render(props) {
    return (
      <svg width={props.r * 2} height={props.r * 2}>
        <circle cx={props.r} cy={props.r} r={props.r} fill={`var(--${props.colour}-9)`} />
      </svg>
    )
  },
})

api.assets

Asset URL resolution. When an educator has uploaded a file (image, dataset, audio) to an internote's asset library, you can resolve it to a public URL here.

render(props, api) {
  const imageUrl = api.assets?.resolveAssetUrl('background.png')
  if (!imageUrl) return null
  return <img src={imageUrl} alt="" />
}

api.assets is null when no asset context is mounted — for example, in a preview or testing environment. Always guard against null before calling resolveAssetUrl.

api.isFullscreen

true when the board is in fullscreen mode. Use it to toggle detail level, show more controls, or adjust layout.

render(props, api) {
  return (
    <div className={api.isFullscreen ? 'layout-full' : 'layout-compact'}>
      {api.isFullscreen && <DetailControls />}
      <MainContent />
    </div>
  )
}

api.scale

Coordinate-to-pixel mapping for elements rendered inside a diagram. Only present when a parent diagram element provides a DiagramScaleProvider. Used when building geometry diagram children.

interface DiagramScale {
  scaleX: (x: number) => number   // data coordinate → pixel
  scaleY: (y: number) => number
  xMin: number
  xMax: number
  yMin: number
  yMax: number
  width: number    // pixel dimensions
  height: number
}

api.interaction

The element-hash-keyed interaction store. This is the lower-level system that api.storage builds on — it stores state keyed by a stable content hash of the element, so the same authored element restores its state across reloads. Most elements should use api.storage rather than api.interaction directly.

api.mode

Always 'board'. The SDK is board-only by design — narrative rendering is handled separately. This field exists for type-checking purposes.