API reference

The complete public surface of grist-widget-sdk. Anything not listed here is internal and may change between minor versions.

Entry points

Import path	Use for
grist-widget-sdk	Primary surface — components, hooks, helpers, types.
grist-widget-sdk/advanced	Lower-level hooks (useGristReady, useGristRowsFromTable, …).
grist-widget-sdk/emulator	Emulator core for storybook/playgrounds.
grist-widget-sdk/emulator/testing	renderWithGrist, presets, test-only helpers.

Components

Symbol	Purpose	Reference
GristWidgetProvider	App-root wiring: grist.ready, contexts, subscriptions.	/api/provider-boundary
GristBoundary	Booting / unavailable / error UI chrome.	/api/provider-boundary

Primary hook

Symbol	Purpose	Reference
useGrist<TRow, TMapped>()	Default surface — selection, writes, options, REST, theme.	/api/use-grist

Slice hooks

Performance-oriented subscriptions to one part of the state.

Symbol	Reference
useGristSelection<TRow, TMapped>()	/api/slice-hooks
useGristWrites()	/api/slice-hooks
useGristStatus()	/api/slice-hooks
useGristTheme()	/api/slice-hooks

Schema

Symbol	Reference
useGristSchema(options?)	/api/use-grist-schema

Helpers

Standalone utilities that don't require the React context.

Symbol	Reference
Value codec	/api/helpers
Safe parsing	/api/helpers
Action builders	/api/helpers
Replica document	/api/helpers
Attachments	/api/helpers
REST	/api/helpers
Column mapping	/api/helpers
Alerts	/api/helpers

Types

A single page listing every exported type, with brief inline doc. See /api/types.

Handshake module

Opt-in FSM view of the widget ↔ Grist handshake (snapshot + capabilities

• heartbeat). The default useGrist().status is a projection over this same machine.

Symbol	Reference
GristHandshakeProvider, useGristHandshakeContext, useGristHandshakeContextOptional	/api/handshake
useGristHandshake, useGristCapabilities	/api/handshake
GristWidgetSnapshot, GristCapabilities, GristLifecycle, GristLink, GristSync, GristConfig, GristAuthz	/api/handshake

Advanced hooks

Opt-in lower-level hooks for use cases the default surface doesn't cover.

Symbol	Reference
useGristReady	/api/advanced
useGristAvailability	/api/advanced
useGristRowsFromTable	/api/advanced
useGristWidgetOptions	/api/advanced

Emulator & testing

Symbol	Reference
createGristEmulator, mountGristEmulator	/api/emulator
renderWithGrist, presets	/api/emulator
parseDocument, parseRowFor, parseRowsFor	/api/emulator