API Reference

Core Functions

renderNode

Renders a JSON node to a React element.

function renderNode(
  node: JsonNode,
  registry: ComponentRegistry,
  context?: RenderContext
): React.ReactNode;

Parameters:

• node: The JSON node to render
• registry: A mapping of component types to React components
• context (optional): Additional context, including event handlers

Returns:

• A React element (or null if the component type is not found in the registry)

transformJsonTree

Transforms a JSON tree using the provided visitors/plugins.

async function transformJsonTree(
  root: JsonNode,
  visitors: TransformVisitor[],
  options?: TransformOptions
): Promise<JsonNode>;

Parameters:

• root: The root JSON node to transform
• visitors: An array of transformation plugins
• options (optional): Configuration options for the transformation
  • order: Traversal order (default: 'depthFirstPre')
  • clone: Whether to clone the input object (default: true)

Returns:

• A promise that resolves to the transformed JSON tree

traverseJsonTree

Generator function that traverses a JSON tree and yields each node, allowing for interactive node inspection and modification.

function* traverseJsonTree(
  root: JsonNode,
  options?: TraverseOptions
): Generator<{node: JsonNode, context: TransformContext}, void, void>;

Parameters:

• root: The root JSON node to traverse
• options (optional): Configuration options for the traversal
  • order: Traversal order (default: 'depthFirstPre')
  • clone: Whether to clone the input object (default: false)
  • nodeTypes: Array of node types to yield (default: all types)

Returns:

• A generator that yields each node along with its context during traversal

Example:

// Traverse and modify nodes
for (const { node, context } of traverseJsonTree(jsonDefinition)) {
  if (node.type === 'Button') {
    node.props = { ...node.props, disabled: true };
  }
}
 
// Filter nodes by type
const inputNodes = traverseJsonTree(jsonDefinition, { nodeTypes: ['Input'] });
for (const { node } of inputNodes) {
  console.log(`Found input: ${node.props?.name}`);
}

Types

JsonNode

Represents a JSON node that can be rendered to a React component.

interface JsonNode {
  type: string;
  props?: Record<string, any>;
  children?: JsonNode[];
  key?: string;
  id?: string;
}

Properties:

• type: The component type name (must exist in the registry)
• props (optional): Component props
• children (optional): Child nodes
• key (optional): React key for reconciliation
• id (optional): Identifier for tracking or reference

ComponentRegistry

A mapping of component types to React components.

type ComponentRegistry = { 
  [typeName: string]: React.ComponentType<any> | string 
};

The keys are the type names used in JSON, and the values are either React components or strings (for native HTML elements).

You can create a registry using the createRegistry function, which automatically includes all HTML elements and special components like Fragment and Portal:

import { createRegistry } from 'react-jsonr';
 
// Create a registry with just your custom components
// All HTML elements, Fragment, and Portal are automatically included
const registry = createRegistry({
  CustomComponent: MyCustomComponent,
  SpecialButton: ({ children, ...props }) => (
    <button className="special-btn" {...props}>{children}</button>
  )
});

TransformVisitor

Plugin interface for transforming the JSON tree.

interface TransformVisitor {
  enter?(node: JsonNode, context: TransformContext): void | Promise<void>;
  exit?(node: JsonNode, context: TransformContext): void | Promise<void>;
}

Methods:

• enter: Called when a node is first encountered (before processing children)
• exit: Called after all children have been processed

TransformContext

Context passed to transform visitors.

interface TransformContext {
  depth: number;
  parent: JsonNode | null;
  index: number;
  skipChildren(): void;
  [key: string]: any;
}

Properties:

• depth: Current depth in the tree
• parent: Parent node (null for the root)
• index: Index of this node in the parent's children array
• skipChildren(): Function to skip traversing this node's children

TransformOptions

Options for transform operations.

interface TransformOptions {
  order?: 'depthFirstPre' | 'depthFirstPost' | 'breadthFirst';
  clone?: boolean;
}

Properties:

• order (optional): Traversal order for the transformation (default: 'depthFirstPre')
• clone (optional): Whether to clone the input before transforming (default: true)

TraverseOptions

Options for traversal using the generator.

interface TraverseOptions extends TransformOptions {
  nodeTypes?: string[];
}

Properties:

• Inherits all properties from TransformOptions
• nodeTypes (optional): Types of nodes to yield (empty array or undefined = all types)
• clone (optional): Whether to clone the input before traversing (default: false)

RenderContext

Context for renderNode.

interface RenderContext {
  eventHandlers?: Record<string, Function>;
  [key: string]: any;
}

Properties:

• eventHandlers (optional): Functions that can be referenced by string names in JSON