react-native

react-native

@json-render/react-native

React Native renderer that converts JSON specs into native mobile component trees with standard components, data binding, visibility, actions, and dynamic props.

Quick Start

import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react-native/schema";
import {
  standardComponentDefinitions,
  standardActionDefinitions,
} from "@json-render/react-native/catalog";
import { defineRegistry, Renderer, type Components } from "@json-render/react-native";
import { z } from "zod";

// Create catalog with standard + custom components
const catalog = defineCatalog(schema, {
  components: {
    ...standardComponentDefinitions,
    Icon: {
      props: z.object({ name: z.string(), size: z.number().nullable(), color: z.string().nullable() }),
      slots: [],
      description: "Icon display",
    },
  },
  actions: standardActionDefinitions,
});

// Register only custom components (standard ones are built-in)
const { registry } = defineRegistry(catalog, {
  components: {
    Icon: ({ props }) => <Ionicons name={props.name} size={props.size ?? 24} />,
  } as Components<typeof catalog>,
});

// Render
function App({ spec }) {
  return (
    <StateProvider initialState={{}}>
      <VisibilityProvider>
        <ActionProvider handlers={{}}>
          <Renderer spec={spec} registry={registry} />
        </ActionProvider>
      </VisibilityProvider>
    </StateProvider>
  );
}

Standard Components

Layout

• Container - wrapper with padding, background, border radius

• Row - horizontal flex layout with gap, alignment

• Column - vertical flex layout with gap, alignment

• ScrollContainer - scrollable area (vertical or horizontal)

• SafeArea - safe area insets for notch/home indicator

• Pressable - touchable wrapper that triggers actions on press

• Spacer - fixed or flexible spacing

• Divider - thin line separator

Content

• Heading - heading text (levels 1-6)

• Paragraph - body text

• Label - small label text

• Image - image display with sizing modes

• Avatar - circular avatar image

• Badge - small status badge

• Chip - tag/chip for categories

Input

• Button - pressable button with variants

• TextInput - text input field

• Switch - toggle switch

• Checkbox - checkbox with label

• Slider - range slider

• SearchBar - search input

Feedback

• Spinner - loading indicator

• ProgressBar - progress indicator

Composite

• Card - card container with optional header

• ListItem - list row with title, subtitle, accessory

• Modal - bottom sheet modal

Visibility Conditions

Use visible on elements. Syntax: { "$state": "/path" }, { "$state": "/path", "eq": value }, { "$state": "/path", "not": true }, [ cond1, cond2 ] for AND.

Pressable + setState Pattern

Use Pressable with the built-in setState action for interactive UIs like tab bars:

{
  "type": "Pressable",
  "props": {
    "action": "setState",
    "actionParams": { "statePath": "/activeTab", "value": "home" }
  },
  "children": ["home-icon", "home-label"]
}

Dynamic Prop Expressions

Any prop value can be a data-driven expression resolved at render time:

• { "$state": "/state/key" } - reads from state model (one-way read)

• { "$bindState": "/path" } - two-way binding: use on the natural value prop (value, checked, pressed, etc.) of form components.

• { "$bindItem": "field" } - two-way binding to a repeat item field. Use inside repeat scopes.

• { "$cond": <condition>, "$then": <value>, "$else": <value> } - conditional value

{
  "type": "TextInput",
  "props": {
    "value": { "$bindState": "/form/email" },
    "placeholder": "Email"
  }
}

Components do not use a statePath prop for two-way binding. Use { "$bindState": "/path" } on the natural value prop instead.

Built-in Actions

The setState action is handled automatically by ActionProvider and updates the state model directly, which re-evaluates visibility conditions and dynamic prop expressions:

{ "action": "setState", "actionParams": { "statePath": "/activeTab", "value": "home" } }

Providers

Provider Purpose

StateProvider Share state across components (JSON Pointer paths). Accepts optional store prop for controlled mode.

ActionProvider Handle actions dispatched from components

VisibilityProvider Enable conditional rendering based on state

ValidationProvider Form field validation

External Store (Controlled Mode)

Pass a StateStore to StateProvider (or JSONUIProvider / createRenderer) to use external state management:

import { createStateStore, type StateStore } from "@json-render/react-native";

const store = createStateStore({ count: 0 });

<StateProvider store={store}>{children}</StateProvider>

store.set("/count", 1); // React re-renders automatically

When store is provided, initialState and onStateChange are ignored.

Key Exports

Export Purpose

defineRegistry Create a type-safe component registry from a catalog

Renderer Render a spec using a registry

schema React Native element tree schema

standardComponentDefinitions Catalog definitions for all standard components

standardActionDefinitions Catalog definitions for standard actions

standardComponents Pre-built component implementations

createStandardActionHandlers Create handlers for standard actions

useStateStore Access state context

useStateValue Get single value from state

useBoundProp Two-way state binding via $bindState/$bindItem

useStateBinding (deprecated) Legacy two-way binding by path

useActions Access actions context

useAction Get a single action dispatch function

useUIStream Stream specs from an API endpoint

createStateStore Create a framework-agnostic in-memory StateStore

StateStore Interface for plugging in external state management

Weekly Installs406Repositoryvercel-labs/json-renderGitHub Stars14.1KFirst SeenMar 7, 2026Security AuditsGen Agent Trust HubPassSocketPassSnykPassInstalled oncodex395opencode389cursor388kimi-cli386gemini-cli386github-copilot386