Storage

Every element gets a namespaced key/value store at api.storage. Use it to persist user state — quiz answers, slider positions, simulation settings, anything that should survive a page reload.

A checkbox that remembers whether it has been ticked:

defineElement({
  kind: 'remember-checkbox',
  category: 'inline',
  render(props, api) {
    const [checked, setChecked] = React.useState(false)

    React.useEffect(() => {
      api.storage.get<boolean>('checked').then((v) => {
        if (v != null) setChecked(v)
      })
    }, [])

    const toggle = async () => {
      const next = !checked
      setChecked(next)
      await api.storage.set('checked', next)
    }

    return (
      <label>
        <input type="checkbox" checked={checked} onChange={toggle} />
        {api.element.body}
      </label>
    )
  },
})

The KeyValueStorage Interface

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

Access the store via api.storage in any render function:

render(props, api) {
  const save = async (answer: string) => {
    await api.storage.set('answer', answer)
  }
  // ...
}

storage.get

Retrieves a stored value. Returns null if nothing has been saved at that key for this user and element.

• key (string) — the key to retrieve.
• Returns Promise<T | null>

React.useEffect(() => {
  api.storage.get<string>('selection').then((saved) => {
    if (saved != null) setSelection(saved)
  })
}, [])

storage.set

Saves a value. Overwrites any existing value at that key. The value must be JSON-serialisable — objects, arrays, strings, numbers, and booleans are all valid. Functions and circular references are not.

• key (string) — the key to write.
• value (T) — the value to store.
• Returns Promise<void>

await api.storage.set('state', { step: 3, answers: [1, 2] })

storage.delete

Removes a saved key. Has no effect if the key does not exist.

• key (string) — the key to remove.
• Returns Promise<void>

await api.storage.delete('draft')

How Storage Is Keyed

State is scoped to the current user, the current internote, and this element instance. The element instance key is derived from a content hash of the element's Chalk attributes and body — not from a position or index. This means:

• The same element restores state correctly when the internote is rearranged
• Duplicate elements have independent storage
• Editing any attribute in Chalk changes the hash, making previously stored state inaccessible for that element

This mirrors the behaviour of built-in interactive elements like multichoice — editing the element's Chalk effectively resets student progress. Document this in your element description so educators are aware.

Patterns

Restore on Mount

Load saved state in a useEffect and apply it before or after calling anything that needs it:

render(props, api) {
  const [value, setValue] = React.useState<number>(props.start)
  const loaded = React.useRef(false)

  React.useEffect(() => {
    if (loaded.current) return
    loaded.current = true
    api.storage.get<number>('value').then((saved) => {
      if (saved != null) setValue(saved)
    })
  }, [])

  const update = async (next: number) => {
    setValue(next)
    await api.storage.set('value', next)
  }

  return <Slider value={value} onChange={update} />
}

Debounced Saves

For high-frequency updates (slider dragging, text input), debounce the save to avoid excessive writes:

const saveTimer = React.useRef<ReturnType<typeof setTimeout>>()

const scheduleAutoSave = (state: AppState) => {
  clearTimeout(saveTimer.current)
  saveTimer.current = setTimeout(async () => {
    try {
      await api.storage.set('state', state)
    } catch (err) {
      console.warn('Storage write failed:', err)
    }
  }, 800)
}

Storage Not Available

In preview or server-rendering contexts, no storage backend is mounted and api.storage falls back to a no-op implementation — reads return null, writes resolve silently. Elements always render correctly; they just start in their default state. You do not need to guard against missing storage.

Storage vs Interaction

api.storage is the plugin-facing key/value API. api.interaction is the lower-level store that api.storage builds on — it persists state as an opaque blob keyed by the element hash. Use api.storage unless you have a specific reason to use api.interaction directly.