json-render/apps/web/app/(main)/docs/registry/page.mdx

export const metadata = { title: "Registry" }

# Registry

A registry maps your [catalog](/docs/catalog) definitions to platform-specific implementations. The catalog defines *what* AI can generate — the registry provides the *how*.

What a registry contains depends on the schema you use. Each package defines its own schema, which determines the shape of both the catalog and the registry.

- **`@json-render/react`** — Components (React elements) and action handlers
- **`@json-render/react-native`** — Components (React Native elements) and action handlers
- **`@json-render/remotion`** — Clip components, transitions, and effects

## @json-render/react

### defineRegistry

Use `defineRegistry` to create a type-safe registry from your catalog. Pass your components, actions, or both:

```tsx
import { defineRegistry } from '@json-render/react';
import { myCatalog } from './catalog';

export const { registry, handlers, executeAction } = defineRegistry(myCatalog, {
  components: {
    Card: ({ props, children }) => (
      <div className="card">
        <h2>{props.title}</h2>
        {props.description && <p>{props.description}</p>}
        {children}
      </div>
    ),

    Button: ({ props, onAction }) => (
      <button onClick={() => onAction?.({ name: props.action })}>
        {props.label}
      </button>
    ),
  },

  actions: {
    submit_form: async (params, setState) => {
      const res = await fetch('/api/submit', {
        method: 'POST',
        body: JSON.stringify(params),
      });
      const result = await res.json();
      setState((prev) => ({ ...prev, formResult: result }));
    },

    export_data: async (params) => {
      const blob = await generateExport(params.format);
      downloadBlob(blob, `export.${params.format}`);
    },
  },
});
```

The returned object contains:

- `registry` — component registry for `<Renderer />`
- `handlers` — factory for ActionProvider-compatible handlers
- `executeAction` — imperative action dispatch (for use outside the React tree)

### Component Props

Each component receives a `ComponentContext` object:

```typescript
interface ComponentContext {
  props: T;                    // Type-safe props from your catalog
  children?: React.ReactNode;  // Rendered children (for slot components)
  onAction?: (action: ActionTrigger) => void;  // Dispatch an action
  loading?: boolean;           // Whether the renderer is in a loading state
}
```

Props are automatically inferred from your catalog, so `props.title` is typed as `string` if your catalog defines it that way.

### Action Handlers

Instead of AI generating arbitrary code, it declares *intent* by name. Your application provides the implementation. This is a core guardrail.

Actions are declared in your [catalog](/docs/catalog). The `@json-render/react` schema supports an `actions` key where you define what operations AI can trigger:

```typescript
import { defineCatalog } from '@json-render/core';
import { schema } from '@json-render/react';
import { z } from 'zod';

const catalog = defineCatalog(schema, {
  components: { /* ... */ },
  actions: {
    submit_form: {
      params: z.object({
        formId: z.string(),
      }),
      description: 'Submit a form',
    },
    export_data: {
      params: z.object({
        format: z.enum(['csv', 'pdf', 'json']),
      }),
    },
    navigate: {
      params: z.object({
        url: z.string(),
      }),
    },
  },
});
```

Action handlers receive `(params, setState, data)` and are defined inside `defineRegistry`:

```tsx
export const { handlers, executeAction } = defineRegistry(catalog, {
  actions: {
    submit_form: async (params, setState) => {
      const response = await fetch('/api/submit', {
        method: 'POST',
        body: JSON.stringify({ formId: params.formId }),
      });
      const result = await response.json();
      setState((prev) => ({ ...prev, formResult: result }));
    },

    export_data: async (params) => {
      const blob = await generateExport(params.format);
      downloadBlob(blob, `export.${params.format}`);
    },

    navigate: (params) => {
      window.location.href = params.url;
    },
  },
});
```

### Data Binding

Use hooks inside your registry components to read and write data:

```tsx
import { useStateStore } from '@json-render/react';
import { getByPath } from '@json-render/core';

// Inside defineRegistry components:

Metric: ({ props }) => {
  const { data } = useStateStore();
  const value = getByPath(data, props.valuePath);

  return (
    <div className="metric">
      <span className="label">{props.label}</span>
      <span className="value">{formatValue(value)}</span>
    </div>
  );
},

TextField: ({ props }) => {
  const { data, set } = useStateStore();
  const value = getByPath(data, props.valuePath) as string;

  return (
    <input
      value={value || ''}
      onChange={(e) => set(props.valuePath, e.target.value)}
      placeholder={props.placeholder}
    />
  );
},
```

### Using the Renderer

Wire everything together with providers and the `<Renderer />` component:

```tsx
import { useMemo, useRef } from 'react';
import {
  Renderer,
  StateProvider,
  VisibilityProvider,
  ActionProvider,
} from '@json-render/react';
import { registry, handlers } from './registry';

function App({ spec, data, setState }) {
  const dataRef = useRef(data);
  const setStateRef = useRef(setState);
  dataRef.current = data;
  setStateRef.current = setState;

  const actionHandlers = useMemo(
    () => handlers(() => setStateRef.current, () => dataRef.current),
    [],
  );

  return (
    <StateProvider initialState={data}>
      <VisibilityProvider>
        <ActionProvider handlers={actionHandlers}>
          <Renderer spec={spec} registry={registry} />
        </ActionProvider>
      </VisibilityProvider>
    </StateProvider>
  );
}
```

## @json-render/react-native

`@json-render/react-native` uses the same `defineRegistry` API. The only difference is that components return React Native elements instead of HTML:

```tsx
import { defineRegistry } from '@json-render/react-native';
import { View, Text, Pressable } from 'react-native';

export const { registry } = defineRegistry(catalog, {
  components: {
    Card: ({ props, children }) => (
      <View style={styles.card}>
        <Text style={styles.title}>{props.title}</Text>
        {children}
      </View>
    ),

    Button: ({ props, emit }) => (
      <Pressable onPress={() => emit?.("press")}>
        <Text>{props.label}</Text>
      </Pressable>
    ),
  },
});
```

See the [@json-render/react-native API reference](/docs/api/react-native) for the full API.

## @json-render/remotion

`@json-render/remotion` takes a different approach. Instead of `defineRegistry`, it uses a plain component registry with built-in standard components for video production:

```tsx
import { Renderer, standardComponents } from '@json-render/remotion';

// Use the standard components directly
<Renderer spec={timelineSpec} components={standardComponents} />

// Or extend with your own
const components = {
  ...standardComponents,
  CustomSlide: ({ clip }) => <AbsoluteFill>{/* ... */}</AbsoluteFill>,
};
```

The Remotion schema also supports `transitions` and `effects` in the catalog rather than actions.

See the [@json-render/remotion API reference](/docs/api/remotion) for the full API.

## Next

Learn about [data binding](/docs/data-binding) for dynamic values.