Simten

Building custom UIs

One simulation from useSimulation, shown with CircuitCanvas or with your own components.

useSimulation runs a circuit in the sandbox and returns { state, actions }. state is what the circuit is doing now; actions is what you can tell it to do. Everything on this page is a different way to show that one simulation, or to drive it, from your React UI. Pick the simplest one that gives you what you need.

These all take a circuit you already have. If instead you want users to edit source and watch it simulate live, an editor beside a canvas, see Code Editor, which pairs CodeEditor with useSimulation.

Embed a circuit

To put a live circuit on a page you don't build with React (a course platform, Notion, a blog, Google Sites), you don't need any of the tiers below. Open the circuit in the editor, click Share, and pick Embed. Choose a size and theme, check the preview, and copy the snippet:

<iframe src="https://embed.simten.dev/s/abc123?theme=auto"
        style="width:100%; aspect-ratio:4/3; border:0"
        title="HalfAdder (Simten)" loading="lazy"></iframe>

Sites that embed by URL take the bare link, https://embed.simten.dev/s/abc123. Two options go on the end of it:

OptionValuesDefault
themelight, dark, auto (follows the reader's system)auto
controls1 shows the clock controls, 0 hides them1

Readers can flip switches and step the clock. Anything that would change the circuit happens on simten.dev: the Open in Simten link opens it in the editor in a new tab. Share links don't expire, so an embed keeps working. How the embed page is isolated is in Security.

Tier 1: The canvas

The default. CircuitCanvas draws the simulation, with a switch for each input and a light for each output, and shows its own loading and error states. ClockControls renders nothing for a circuit without a clock, so it's safe to put next to any canvas.

import '@simten/react/styles.css'
import { CircuitCanvas, ClockControls, useSimulation } from '@simten/react'

function HalfAdderDemo() {
  const sim = useSimulation(HalfAdder)
  return (
    <>
      <CircuitCanvas simulation={sim} height={300} />
      <ClockControls simulation={sim} />
    </>
  )
}

Clicking a switch calls the simulation's actions, and double-clicking a component opens its insides. The cards around circuits on simten.dev are this, with a title bar and a Fork button that belong to the site.

Tier 2: Siblings read the same state

When another component should react to the circuit (a truth-table row that follows the switches, a readout of one output), give it the same state. There's one simulation, so the canvas and the table can't disagree.

import { CircuitCanvas, useSimulation } from '@simten/react'
import { TruthTable, computeActiveRow } from '@/components/TruthTable'

function HalfAdderWithLiveTable() {
  const sim = useSimulation(HalfAdder)
  const activeRow = computeActiveRow(sim.state.portValues, COLUMNS, ROWS)

  return (
    <>
      <CircuitCanvas simulation={sim} height={300} />
      <TruthTable columns={COLUMNS} rows={ROWS} highlightRow={activeRow} />
    </>
  )
}

Live demo: toggle the switches:

Compiling...
Half adder
Toggle the switches, and the truth table row follows.
Half adder truth table
absumcarry
0000
0110
1010
1101

state.outputs has the circuit's outputs by name (sim.state.outputs.sum), typed from the circuit. state is a new object on every update and holds only settled values: the sandbox never reports a circuit halfway through propagating. Before the first update state.ready is false and portValues is null, so plan for that first frame.

The /learn/adders page uses this for its live truth tables.

Tier 3: Siblings drive it

When something outside the canvas should change the inputs (clicking a row in a truth table sets the switches to that combination), call the same actions:

<TruthTable
  ...
  onRowClick={(row) => void sim.actions.set({ a: row[0], b: row[1] })}
/>

set takes input port names and the paths of Switch and Input nodes, the things a person at the board could change, and writes them all before the circuit settles, so nothing sees them change one at a time. toggle('a') flips one 1-bit input. A key that names anything else, a register say, is an error, reported in state.error.

Tier 4: No canvas at all

When the schematic isn't what you want to show, leave CircuitCanvas out and render whatever React you want from state and actions. The circuit becomes your engine; your component is the UI.

import { useSimulation } from '@simten/react'

function HalfAdderWithCustomControls() {
  const { state, actions } = useSimulation(HalfAdder)
  const { sum, carry } = state.outputs

  return (
    <>
      <ToggleControl label="a" onToggle={() => actions.toggle('a')} />
      <ToggleControl label="b" onToggle={() => actions.toggle('b')} />
      <LedReadout lit={sum === 1} label="sum" />
      <LedReadout lit={carry === 1} label="carry" />
    </>
  )
}

Live demo: the same HalfAdder as tier 2, rendered as toggle buttons and LED indicators instead of a schematic:

a0
b0
sum
0
carry
0
Half adder truth table
absumcarry
0000
0110
1010
1101

The simulator is still doing real work: compiling, propagating and reporting values through the sandbox iframe. You could equally render nothing at all and use it as a background engine (a checksum verifier, an audio-rate signal generator wired to WebAudio).

Two examples of tier 4 on simten.dev itself:

  • Snake: the circuit is the game engine (DualPortRAM framebuffer, 4-phase pipeline, collision detection); the React component renders a custom 8×8 pixel grid + D-pad + speed slider on top of the sim.
  • RV32I CPU debugger: a 5-stage pipelined RISC-V processor on the engine side, with a debugger UI on top: register file, memory view, pipeline-stage indicators, instruction stream.

One sandbox per page

Every useSimulation on a page shares one sandbox, created by the first one. Each circuit is a session in it, with its own state. A SandboxProvider with no client gives everything under it a sandbox of its own, which is worth it only for a heavy circuit that should run on its own core.

Security

Composing the pieces yourself doesn't bypass anything: useSimulation routes every simulation through the same cross-origin sandbox iframe. See Security architecture for the full picture (origin isolation, Web Worker thread isolation, CSP, postMessage boundary).

Which tier do I pick?

TierPick whenAPI
1You want a circuit on a pageuseSimulation + CircuitCanvas + ClockControls
2A sibling reacts to the circuitread state
3A sibling drives the circuitcall actions.set
4You want your own frontendstate and actions, no canvas

On this page