React Widget API

Complete API reference for @gnata-sqlite/react — hooks, components, theme, and utilities

npm install @gnata-sqlite/react
npx @gnata-sqlite/react setup ./public

Hooks

`useJsonataLsp(options?)`

Loads the LSP WASM module for editor features (diagnostics, autocomplete, hover). Works with zero configuration after running the setup command above.

const lsp = useJsonataLsp()
// or with custom URLs:
const lsp = useJsonataLsp({ lspWasmUrl: '/custom/gnata-lsp.wasm', lspExecUrl: '/custom/lsp-wasm_exec.js' })

Option	Type	Default	Description
`lspWasmUrl`	`string`	`'/gnata-lsp.wasm'`	URL to `gnata-lsp.wasm`
`lspExecUrl`	`string`	`'/lsp-wasm_exec.js'`	URL to `lsp-wasm_exec.js`

Returns WasmState (see below).

`useJsonataWasm(options?)`

Full WASM loader — loads LSP by default, plus the optional eval engine. Use useJsonataLsp for the common case; use this hook only when client-side evaluation is needed.

Option	Type	Default	Description
`evalWasmUrl`	`string`	—	URL to `gnata.wasm` (opt-in, ~5.3MB)
`evalExecUrl`	`string`	—	URL to `wasm_exec.js` (required with evalWasmUrl)
`lspWasmUrl`	`string`	`'/gnata-lsp.wasm'`	URL to `gnata-lsp.wasm`
`lspExecUrl`	`string`	`'/lsp-wasm_exec.js'`	URL to `lsp-wasm_exec.js`

Returns WasmState:

Field	Type	Description
`isReady`	`boolean`	Eval module loaded
`isLspReady`	`boolean`	LSP module loaded
`error`	`Error \| null`	Loading error
`gnataEval`	`(expr, json) => string`	Evaluate expression
`gnataCompile`	`(expr) => string`	Compile to AST JSON
`gnataDiagnostics`	`(doc) => string`	Get parse diagnostics
`gnataCompletions`	`(doc, pos, schema) => string`	Get completions
`gnataHover`	`(doc, pos, schema) => string \| null`	Get hover info

`useJsonataEval(expression, inputJson, gnataEval, debounceMs?)`

Evaluates an expression with debouncing (default 300ms).

Argument	Type	Description
`expression`	`string`	JSONata expression to evaluate
`inputJson`	`string`	JSON input data
`gnataEval`	`((expr, data) => string) \| null`	The `gnataEval` function from `useJsonataWasm`, or `null` if not yet loaded
`debounceMs`	`number`	Optional debounce delay in ms (default 300)

// Requires the eval engine (opt-in, build from source)
const wasm = useJsonataWasm({ evalWasmUrl: '/gnata.wasm', evalExecUrl: '/wasm_exec.js' })
const { result, error, isSuccess, timing, timingMs, evaluate } =
  useJsonataEval(expression, inputJson, wasm.gnataEval)

Returns JsonataEvalResult:

Field	Type	Description
`result`	`string`	Formatted result
`error`	`string \| null`	Error message
`isSuccess`	`boolean`	Whether evaluation succeeded
`timing`	`string`	Human-readable evaluation time (e.g. `"12ms"`)
`timingMs`	`number`	Evaluation time in ms
`evaluate`	`() => void`	Manually trigger evaluation

`useJsonataSchema(inputJson)`

Builds autocomplete schema from JSON data. Memoized.

Returns: Schema object for autocomplete.

`useJsonataEditor(options)`

Low-level hook creating a CodeMirror 6 EditorView.

Option	Type	Required	Description
`containerRef`	`RefObject<HTMLElement>`	yes	Ref to the container element
`initialDoc`	`string`	no	Initial editor content
`placeholder`	`string`	no	Placeholder text
`onChange`	`(value: string) => void`	no	Content change callback
`onRun`	`() => void`	no	Cmd+Enter callback
`theme`	`'dark' \| 'light'`	no	Color theme
`themeOverrides`	`object`	no	Override specific theme tokens
`themeExtensions`	`Extension[]`	no	Replace built-in theme with custom extensions
`gnataEval`	`(expr, json) => string`	no	Eval function from WASM
`gnataDiagnostics`	`(doc) => string`	no	Diagnostics function from WASM
`gnataCompletions`	`(doc, pos, schema) => string`	no	Completions function from WASM
`gnataHover`	`(doc, pos, schema) => string \| null`	no	Hover function from WASM
`getInputJson`	`() => string`	no	Current input JSON for autocomplete
`schema`	`Schema`	no	Schema object for autocomplete
`lineNumbers`	`boolean`	no	Show line numbers

Returns: { view: EditorView | null, getValue: () => string, setValue: (value: string) => void, setTheme: (theme: 'dark' | 'light') => void }

`useJsonataLsp(options?)`

Documented above — this is the recommended hook for most use cases.

Components

`<JsonataPlayground>`

Full three-panel widget: expression + input + result.

Prop	Type	Default	Description
`defaultExpression`	`string`	`''`	Initial expression
`defaultInput`	`string`	`'{}'`	Initial JSON input
`wasmOptions`	`UseJsonataWasmOptions`	—	Options passed to `useJsonataWasm` internally
`theme`	`'dark' \| 'light'`	`'dark'`	Color theme
`height`	`number`	`400`	Panel height in px
`className`	`string`	—	CSS class for the container
`style`	`CSSProperties`	—	Inline styles for the container

`<JsonataEditor>`

Expression editor with optional WASM features.

Prop	Type	Default	Description
`value`	`string`	—	Controlled value
`onChange`	`(value: string) => void`	—	Change callback
`schema`	`Schema`	—	Schema object for autocomplete
`gnataEval`	`(expr, json) => string`	—	Eval function from WASM
`gnataDiagnostics`	`(doc) => string`	—	Diagnostics function from WASM
`gnataCompletions`	`(doc, pos, schema) => string`	—	Completions function from WASM
`gnataHover`	`(doc, pos, schema) => string \| null`	—	Hover function from WASM
`themeExtensions`	`Extension[]`	—	Replace built-in theme with custom extensions
`theme`	`'dark' \| 'light'`	`'dark'`	Color theme
`placeholder`	`string`	—	Placeholder text
`getInputJson`	`() => string`	—	For introspective autocomplete
`onRun`	`() => void`	—	Cmd+Enter callback

`<JsonataInput>`

JSON input editor.

Prop	Type	Default	Description
`value`	`string`	—	Controlled value
`onChange`	`(value: string) => void`	—	Change callback
`theme`	`'dark' \| 'light'`	`'dark'`	Color theme

`<JsonataResult>`

Read-only result display.

Prop	Type	Default	Description
`value`	`string \| null`	—	Result (green)
`error`	`string \| null`	—	Error (red)
`timing`	`string`	—	Human-readable eval time
`theme`	`'dark' \| 'light'`	`'dark'`	Color theme

Theme

`tokyoNightTheme(mode)`

Returns CodeMirror extensions for the Tokyo Night theme.

import { tokyoNightTheme } from '@gnata-sqlite/react'
const extensions = [tokyoNightTheme('dark')]

`tooltipTheme(mode)`

Returns a standalone tooltip styling extension. Useful for applying consistent tooltip styles outside the main theme.

import { tooltipTheme } from '@gnata-sqlite/react'
const extensions = [tooltipTheme('dark')]

Color exports

import { darkColors, lightColors, darkTokenColors, lightTokenColors } from '@gnata-sqlite/react'

darkColors / lightColors — UI colors (bg, surface, text, accent, green, error, border, etc.)
darkTokenColors / lightTokenColors — Syntax token colors (keyword, string, number, function, property, operator, etc.)

Utilities

Export	Description
`jsonataStreamLanguage`	CodeMirror `StreamLanguage` for JSONata
`buildSchema(json)`	Build autocomplete schema from JSON
`collectKeys(obj, map, depth)`	Recursively collect object keys
`allKeysFromJson(json, partial)`	Get completion items from JSON string
`formatHoverMarkdown(md)`	Convert LSP hover markdown to HTML
`formatTiming(ms)`	Format milliseconds to readable string

React Widget API

On this page