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:
| Option | Values | Default |
|---|---|---|
theme | light, dark, auto (follows the reader's system) | auto |
controls | 1 shows the clock controls, 0 hides them | 1 |
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:
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:
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 (
DualPortRAMframebuffer, 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?
| Tier | Pick when | API |
|---|---|---|
| 1 | You want a circuit on a page | useSimulation + CircuitCanvas + ClockControls |
| 2 | A sibling reacts to the circuit | read state |
| 3 | A sibling drives the circuit | call actions.set |
| 4 | You want your own frontend | state and actions, no canvas |