SDK
A tiny, typed, batteries-included surface that turns the Grist plugin API into idiomatic React.
grist-widget-sdk wraps the Grist plugin API — the JavaScript bridge
between a custom widget iframe and a Grist document — into one hook, a
provider, and a boundary. Start with the Guide
for the mental model, or jump straight to a symbol in the
API reference.
Singleton hook
A single useGrist() handles all Grist states to avoid race conditions and code drift.
Robust handshake
Provider, boundary, and modes for clean errors and status management within your app.
Decoded values
JS-native cell shapes with explicit types, errors and safe parsing.
Mapped columns
mappedRecord and mapBack for simple read/write on Grist tables.
Cookbook
Ten end-to-end recipes — and the working demo widgets behind each one.
Design rationale
Why the API looks the way it does — for teams evaluating the trade-offs.
Sections
CLI reference
`npm create grist-widget` — what it scaffolds, and how the bundled GitHub Pages deploy pipeline works.
What is `grist-widget-sdk`?
`grist-widget-sdk` is a React library that wraps the Grist plugin API — the JavaScript bridge between a custom widget iframe and a Grist document. Its goal is one thing: