grist-widget-sdkReact SDK for Grist custom widgets

A tiny, typed, batteries-included surface that turns the Grist plugin API into idiomatic React.

🪝

Singleton hook

A single useGrist() handles all Grist states to avoid race conditions and code drift.

useGrist

🤝

Robust handshake

Provider, boundary, and modes for clean errors and status management within your app.

Provider & boundary

🔤

Decoded values

JS-native cell shapes with explicit types, errors and safe parsing.

Reading data

🗺️

Mapped columns

mappedRecord and mapBack for simple read/write on Grist tables

Column mapping

✏️

Quickstart

Two-minute Vite scaffold, then cookbook recipes for the shapes you'll actually build.

Start here

🎬

Demos

Working widgets you can paste into a Grist Custom Widget section and try today.

See demos

📐

Design rationale

Why the API looks the way it does — for teams evaluating the trade-offs.

🤖

Agent guide

For AI-assisted workflows — tasks, commands, and pitfalls in one place.

For agents

Compare with the raw plugin API · Testing without Grist

What it looks like

The hello-world demo is the whole idea in a handful of lines. The playground shell handles Grist setup; you only write:

tsx

import { useGrist, type UseGristOptions } from "grist-widget-sdk"

export const GRIST_OPTIONS: UseGristOptions = {
  requiredAccess: "read table",
}

export function WidgetApp() {
  const w = useGrist()
  const rowKey =
    w.record && typeof w.record.id === "number" ? String(w.record.id) : w.mode

  if (w.mode === "empty") return <p>Select a row.</p>
  if (w.mode === "new-row") return <p>New row flow</p>
  return <p key={rowKey}>Selected row #{String(w.record!.id)}</p>
}

Try it live · Source on GitHub

Start with Vite

bash

npx degit ArthurBlanchon/grist-widget-sdk/templates/grist-widget-template-vite my-widget
cd my-widget
pnpm install
pnpm dev

See Getting started for templates, typing, and local testing.