The Element SDK is in beta and not yet publicly released — APIs may change without notice.

Toolbar

Add buttons and toggles to the board toolbar from environment and hybrid elements

Environment and hybrid elements can integrate with the board toolbar — the strip that appears at the top of the board containing playback controls, scene navigation, and the fullscreen toggle. Your element contributes buttons, toggles, and separators declaratively by implementing the toolbar field on your definition.

toolbar?: (api: ToolbarApi, props: P) => ToolbarContribution[]

toolbar?: (api: ToolbarApi, props: P) => ToolbarContribution[]

TypeScript

Read-only

The function receives:

api — board-level capabilities (fullscreen state and control)
props — your element's resolved schema props

It returns an array of ToolbarContribution objects, which the nearest ToolbarHost renders alongside the built-in controls. The function is called on every render, so you can derive button states and disabled conditions from props directly.

export default defineElement({
  kind: 'simulation',
  category: 'environment',
  toolbar(api, props) {
    return [
      {
        type: 'button',
        id: 'reset',
        label: 'Reset',
        onClick: () => resetSimulation(),
      },
      { type: 'separator' },
      {
        type: 'toggle',
        id: 'gravity',
        label: 'Gravity',
        active: gravityEnabled,
        onToggle: () => setGravityEnabled(!gravityEnabled),
      },
    ]
  },
  renderEnvironment(props, api) { ... },
})

export default defineElement({
  kind: 'simulation',
  category: 'environment',
  toolbar(api, props) {
    return [
      {
        type: 'button',
        id: 'reset',
        label: 'Reset',
        onClick: () => resetSimulation(),
      },
      { type: 'separator' },
      {
        type: 'toggle',
        id: 'gravity',
        label: 'Gravity',
        active: gravityEnabled,
        onToggle: () => setGravityEnabled(!gravityEnabled),
      },
    ]
  },
  renderEnvironment(props, api) { ... },
})

tsx

Read-only

The toolbar function is called with the render props but outside the component lifecycle — it cannot use hooks. Read state from a ref or closure rather than useState.

ToolbarApi

Provides access to board-level fullscreen controls:

interface ToolbarApi {
  isFullscreen: boolean
  requestFullscreen?: () => void
  exitFullscreen?: () => void
}

interface ToolbarApi {
  isFullscreen: boolean
  requestFullscreen?: () => void
  exitFullscreen?: () => void
}

TypeScript

Read-only

Use api.isFullscreen to show or hide controls that only make sense in one mode, and requestFullscreen / exitFullscreen to drive fullscreen from inside the toolbar:

toolbar(api, props) {
  return [
    {
      type: 'button',
      id: 'fullscreen-toggle',
      icon: api.isFullscreen ? 'exit-fullscreen' : 'fullscreen',
      label: api.isFullscreen ? 'Exit fullscreen' : 'Fullscreen',
      onClick: api.isFullscreen
        ? () => api.exitFullscreen?.()
        : () => api.requestFullscreen?.(),
    },
  ]
}

toolbar(api, props) {
  return [
    {
      type: 'button',
      id: 'fullscreen-toggle',
      icon: api.isFullscreen ? 'exit-fullscreen' : 'fullscreen',
      label: api.isFullscreen ? 'Exit fullscreen' : 'Fullscreen',
      onClick: api.isFullscreen
        ? () => api.exitFullscreen?.()
        : () => api.requestFullscreen?.(),
    },
  ]
}

tsx

Read-only

Contribution Types

ToolbarButton

A clickable action button.

{
  type: 'button',
  id: 'export',
  icon: 'copy',        // built-in icon name or ReactElement
  label: 'Export',
  onClick: () => exportData(),
  disabled: false,
}

{
  type: 'button',
  id: 'export',
  icon: 'copy',        // built-in icon name or ReactElement
  label: 'Export',
  onClick: () => exportData(),
  disabled: false,
}

TypeScript

Read-only

id (string; required) — Stable identifier. Must be unique within your contributions.
icon (string or ReactElement; optional) — A built-in icon name ('play', 'copy', 'check', etc.) or a custom ReactElement.
label (string; optional) — Tooltip or visible label text.
onClick (function; required) — Callback fired when clicked.
disabled (boolean; optional) — Greys out the button and blocks clicks.

ToolbarToggle

A two-state button that shows an active/inactive state.

{
  type: 'toggle',
  id: 'show-labels',
  label: 'Labels',
  active: showLabels,
  onToggle: () => setShowLabels(!showLabels),
}

{
  type: 'toggle',
  id: 'show-labels',
  label: 'Labels',
  active: showLabels,
  onToggle: () => setShowLabels(!showLabels),
}

TypeScript

Read-only

id (string; required) — Stable identifier.
icon (string or ReactElement; optional) — Built-in icon name or ReactElement.
label (string; optional) — Tooltip or visible label text.
active (boolean; required) — Whether the toggle is currently on.
onToggle (function; required) — Callback fired when the toggle is clicked.
disabled (boolean; optional) — Prevents interaction.

ToolbarSeparator

A visual divider between groups of controls.

{ type: 'separator' }

{ type: 'separator' }

TypeScript

Read-only

ToolbarCustom

An escape hatch that renders arbitrary content into a toolbar slot. Use sparingly — prefer button and toggle for standard controls.

{
  type: 'custom',
  id: 'step-counter',
  render: () => <span className="step-label">Step {step} of {total}</span>,
}

{
  type: 'custom',
  id: 'step-counter',
  render: () => <span className="step-label">Step {step} of {total}</span>,
}

TypeScript

Read-only

Built-in Icon Names

These icon names are available for the icon field on buttons and toggles:

play pause restart loop next prev fullscreen exit-fullscreen copy check

Pass any ReactElement for icons outside this set:

{
  type: 'button',
  id: 'export',
  icon: <svg>...</svg>,
  onClick: () => exportData(),
}

{
  type: 'button',
  id: 'export',
  icon: <svg>...</svg>,
  onClick: () => exportData(),
}

TypeScript

Read-only

Full Example

An environment element that controls a step-through simulation:

let step = 0
const totalSteps = 5

export default defineElement({
  kind: 'step-sim',
  category: 'environment',
  toolbar(api, props) {
    return [
      {
        type: 'button',
        id: 'prev',
        icon: 'prev',
        label: 'Previous',
        onClick: () => { step = Math.max(0, step - 1); renderStep(step) },
        disabled: step === 0,
      },
      {
        type: 'button',
        id: 'next',
        icon: 'next',
        label: 'Next',
        onClick: () => { step = Math.min(totalSteps - 1, step + 1); renderStep(step) },
        disabled: step === totalSteps - 1,
      },
      { type: 'separator' },
      {
        type: 'button',
        id: 'restart',
        icon: 'restart',
        label: 'Reset',
        onClick: () => { step = 0; renderStep(0) },
      },
    ]
  },
  renderEnvironment(props, api) {
    return <StepSimulation step={step} total={totalSteps} />
  },
})

let step = 0
const totalSteps = 5

export default defineElement({
  kind: 'step-sim',
  category: 'environment',
  toolbar(api, props) {
    return [
      {
        type: 'button',
        id: 'prev',
        icon: 'prev',
        label: 'Previous',
        onClick: () => { step = Math.max(0, step - 1); renderStep(step) },
        disabled: step === 0,
      },
      {
        type: 'button',
        id: 'next',
        icon: 'next',
        label: 'Next',
        onClick: () => { step = Math.min(totalSteps - 1, step + 1); renderStep(step) },
        disabled: step === totalSteps - 1,
      },
      { type: 'separator' },
      {
        type: 'button',
        id: 'restart',
        icon: 'restart',
        label: 'Reset',
        onClick: () => { step = 0; renderStep(0) },
      },
    ]
  },
  renderEnvironment(props, api) {
    return <StepSimulation step={step} total={totalSteps} />
  },
})

tsx

Read-only

On this page

The toolbar Function ToolbarApi Contribution Types Built-in Icon Names Full Example

The Element SDK is in beta and not yet publicly released — APIs may change without notice.

Toolbar

Add buttons and toggles to the board toolbar from environment and hybrid elements

toolbar?: (api: ToolbarApi, props: P) => ToolbarContribution[]

toolbar?: (api: ToolbarApi, props: P) => ToolbarContribution[]

TypeScript

Read-only

The function receives:

api — board-level capabilities (fullscreen state and control)
props — your element's resolved schema props

export default defineElement({
  kind: 'simulation',
  category: 'environment',
  toolbar(api, props) {
    return [
      {
        type: 'button',
        id: 'reset',
        label: 'Reset',
        onClick: () => resetSimulation(),
      },
      { type: 'separator' },
      {
        type: 'toggle',
        id: 'gravity',
        label: 'Gravity',
        active: gravityEnabled,
        onToggle: () => setGravityEnabled(!gravityEnabled),
      },
    ]
  },
  renderEnvironment(props, api) { ... },
})

export default defineElement({
  kind: 'simulation',
  category: 'environment',
  toolbar(api, props) {
    return [
      {
        type: 'button',
        id: 'reset',
        label: 'Reset',
        onClick: () => resetSimulation(),
      },
      { type: 'separator' },
      {
        type: 'toggle',
        id: 'gravity',
        label: 'Gravity',
        active: gravityEnabled,
        onToggle: () => setGravityEnabled(!gravityEnabled),
      },
    ]
  },
  renderEnvironment(props, api) { ... },
})

tsx

Read-only

The toolbar function is called with the render props but outside the component lifecycle — it cannot use hooks. Read state from a ref or closure rather than useState.

ToolbarApi

Provides access to board-level fullscreen controls:

interface ToolbarApi {
  isFullscreen: boolean
  requestFullscreen?: () => void
  exitFullscreen?: () => void
}

interface ToolbarApi {
  isFullscreen: boolean
  requestFullscreen?: () => void
  exitFullscreen?: () => void
}

TypeScript

Read-only

Use api.isFullscreen to show or hide controls that only make sense in one mode, and requestFullscreen / exitFullscreen to drive fullscreen from inside the toolbar:

toolbar(api, props) {
  return [
    {
      type: 'button',
      id: 'fullscreen-toggle',
      icon: api.isFullscreen ? 'exit-fullscreen' : 'fullscreen',
      label: api.isFullscreen ? 'Exit fullscreen' : 'Fullscreen',
      onClick: api.isFullscreen
        ? () => api.exitFullscreen?.()
        : () => api.requestFullscreen?.(),
    },
  ]
}

toolbar(api, props) {
  return [
    {
      type: 'button',
      id: 'fullscreen-toggle',
      icon: api.isFullscreen ? 'exit-fullscreen' : 'fullscreen',
      label: api.isFullscreen ? 'Exit fullscreen' : 'Fullscreen',
      onClick: api.isFullscreen
        ? () => api.exitFullscreen?.()
        : () => api.requestFullscreen?.(),
    },
  ]
}

tsx

Read-only

Contribution Types

ToolbarButton

A clickable action button.

{
  type: 'button',
  id: 'export',
  icon: 'copy',        // built-in icon name or ReactElement
  label: 'Export',
  onClick: () => exportData(),
  disabled: false,
}

{
  type: 'button',
  id: 'export',
  icon: 'copy',        // built-in icon name or ReactElement
  label: 'Export',
  onClick: () => exportData(),
  disabled: false,
}

TypeScript

Read-only

id (string; required) — Stable identifier. Must be unique within your contributions.
icon (string or ReactElement; optional) — A built-in icon name ('play', 'copy', 'check', etc.) or a custom ReactElement.
label (string; optional) — Tooltip or visible label text.
onClick (function; required) — Callback fired when clicked.
disabled (boolean; optional) — Greys out the button and blocks clicks.

ToolbarToggle

A two-state button that shows an active/inactive state.

{
  type: 'toggle',
  id: 'show-labels',
  label: 'Labels',
  active: showLabels,
  onToggle: () => setShowLabels(!showLabels),
}

{
  type: 'toggle',
  id: 'show-labels',
  label: 'Labels',
  active: showLabels,
  onToggle: () => setShowLabels(!showLabels),
}

TypeScript

Read-only

id (string; required) — Stable identifier.
icon (string or ReactElement; optional) — Built-in icon name or ReactElement.
label (string; optional) — Tooltip or visible label text.
active (boolean; required) — Whether the toggle is currently on.
onToggle (function; required) — Callback fired when the toggle is clicked.
disabled (boolean; optional) — Prevents interaction.

ToolbarSeparator

A visual divider between groups of controls.

{ type: 'separator' }

{ type: 'separator' }

TypeScript

Read-only

ToolbarCustom

An escape hatch that renders arbitrary content into a toolbar slot. Use sparingly — prefer button and toggle for standard controls.

{
  type: 'custom',
  id: 'step-counter',
  render: () => <span className="step-label">Step {step} of {total}</span>,
}

{
  type: 'custom',
  id: 'step-counter',
  render: () => <span className="step-label">Step {step} of {total}</span>,
}

TypeScript

Read-only

Built-in Icon Names

These icon names are available for the icon field on buttons and toggles:

play pause restart loop next prev fullscreen exit-fullscreen copy check

Pass any ReactElement for icons outside this set:

{
  type: 'button',
  id: 'export',
  icon: <svg>...</svg>,
  onClick: () => exportData(),
}

{
  type: 'button',
  id: 'export',
  icon: <svg>...</svg>,
  onClick: () => exportData(),
}

TypeScript

Read-only

Full Example

An environment element that controls a step-through simulation:

let step = 0
const totalSteps = 5

export default defineElement({
  kind: 'step-sim',
  category: 'environment',
  toolbar(api, props) {
    return [
      {
        type: 'button',
        id: 'prev',
        icon: 'prev',
        label: 'Previous',
        onClick: () => { step = Math.max(0, step - 1); renderStep(step) },
        disabled: step === 0,
      },
      {
        type: 'button',
        id: 'next',
        icon: 'next',
        label: 'Next',
        onClick: () => { step = Math.min(totalSteps - 1, step + 1); renderStep(step) },
        disabled: step === totalSteps - 1,
      },
      { type: 'separator' },
      {
        type: 'button',
        id: 'restart',
        icon: 'restart',
        label: 'Reset',
        onClick: () => { step = 0; renderStep(0) },
      },
    ]
  },
  renderEnvironment(props, api) {
    return <StepSimulation step={step} total={totalSteps} />
  },
})

let step = 0
const totalSteps = 5

export default defineElement({
  kind: 'step-sim',
  category: 'environment',
  toolbar(api, props) {
    return [
      {
        type: 'button',
        id: 'prev',
        icon: 'prev',
        label: 'Previous',
        onClick: () => { step = Math.max(0, step - 1); renderStep(step) },
        disabled: step === 0,
      },
      {
        type: 'button',
        id: 'next',
        icon: 'next',
        label: 'Next',
        onClick: () => { step = Math.min(totalSteps - 1, step + 1); renderStep(step) },
        disabled: step === totalSteps - 1,
      },
      { type: 'separator' },
      {
        type: 'button',
        id: 'restart',
        icon: 'restart',
        label: 'Reset',
        onClick: () => { step = 0; renderStep(0) },
      },
    ]
  },
  renderEnvironment(props, api) {
    return <StepSimulation step={step} total={totalSteps} />
  },
})

tsx

Read-only

On this page

The toolbar Function ToolbarApi Contribution Types Built-in Icon Names Full Example