Emulator
Run and preview widgets without a live Grist document, in tests and in the browser-based playground.
grist-widget-sdk/emulator is a self-contained reimplementation of the
parts of the Grist plugin API the SDK uses. It installs as window.grist,
so your widget's real code path runs unmodified — no mocking useGrist()
itself.
Testing
renderWithGrist, presets, and custom matchers for vitest/Jest.
Emulator API
createGristEmulator, mountGristEmulator, and the mutator/inspection surface.
Try it without writing anything
The Playground app runs every one of the SDK's example widgets against this same emulator, in an iframe, with no real Grist document needed — the fastest way to see a widget's actual behavior (selection modes, writes, mapped columns) before you touch code.
Where it's used
| Use case | Transport | Entry point |
|---|---|---|
| Unit tests (vitest jsdom) | inline | renderWithGrist — see Testing |
| Storybook / IDE preview | inline | createGristEmulator({ transport: { kind: "inline" } }) |
| The Playground app | iframe | mountGristEmulator — see Emulator API |
Where to go next
- Testing —
renderWithGristand the recommended test patterns. - Emulator API — the lower-level
createGristEmulator/mountGristEmulatorsurface. - Replica document — the document
shape the emulator (and
presets) build on.