json-schema-builder-react

JSON Schema Builder

A beautiful, interactive React component for building and editing JSON schemas visually. Built with TypeScript, Tailwind CSS, and Radix UI.

• 📖 View demo

Features

• 🎨 Visual Editor - Build JSON schemas with an intuitive interface
• 📝 Full JSON Schema Support - Support for all JSON Schema types and constraints
• 🎯 Type-Safe - Written in TypeScript with full type definitions
• ✅ Controlled Component - Full control over state management
• 🎨 Customizable - Flexible API with extensive customization options
• 🌗 Theme Support - Built-in dark mode support
• ⚡ Lightweight - Minimal bundle size with focused API

Installation

npm install json-schema-builder-react
# or
yarn add json-schema-builder-react
# or
pnpm add json-schema-builder-react

Prerequisites

This library requires the following peer dependencies to be installed in your project:

1. Install shadcn/ui Components

This library uses shadcn/ui components. You'll need to set up shadcn/ui and install the required components:

# Initialize shadcn/ui (if not already done)
npx shadcn@latest init

# Install required components
npx shadcn@latest add button dialog input select checkbox tooltip card label textarea

2. Install Radix UI and Utility Libraries

npm install @radix-ui/react-checkbox @radix-ui/react-dialog @radix-ui/react-label @radix-ui/react-select @radix-ui/react-slot @radix-ui/react-tooltip lucide-react class-variance-authority clsx tailwind-merge

3. Tailwind CSS Setup

This library uses Tailwind CSS utility classes. You'll need Tailwind CSS configured in your project.

1. Install Tailwind CSS (if not already installed)

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

2. Configure Tailwind Content Paths

Add the library to your tailwind.config.js:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './src/**/*.{js,jsx,ts,tsx}',
    './node_modules/json-schema-builder-react/**/*.{js,jsx}',  // Add this line
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};

3. Configure PostCSS

Create or update postcss.config.js in your project root:

export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

4. Import Tailwind in your CSS

Add to your main CSS file (e.g., src/index.css):

@tailwind base;
@tailwind components;
@tailwind utilities;

Note: The library components will automatically use your project's Tailwind theme (colors, spacing, etc.).

Usage

Basic Example

import { useState } from 'react';
import { JsonSchemaBuilder } from 'json-schema-builder-react';

function App() {
  const [schema, setSchema] = useState({
    type: 'object',
    properties: {},
    required: []
  });

  return (
    <JsonSchemaBuilder 
      schema={schema}
      onChange={setSchema}
    />
  );
}

With Initial Schema

import { useState } from 'react';
import { JsonSchemaBuilder } from 'json-schema-builder-react';

function App() {
  const [schema, setSchema] = useState({
    type: 'object',
    title: 'User Profile',
    properties: {
      name: { 
        type: 'string',
        minLength: 2,
        maxLength: 50
      },
      age: { 
        type: 'integer',
        minimum: 0,
        maximum: 120
      }
    },
    required: ['name']
  });

  return (
    <JsonSchemaBuilder 
      schema={schema}
      onChange={(newSchema) => {
        setSchema(newSchema);
        // Save to backend, localStorage, etc.
        localStorage.setItem('schema', JSON.stringify(newSchema));
      }}
    />
  );
}

Customized Layout

import { useState } from 'react';
import { JsonSchemaBuilder } from 'json-schema-builder-react';

function App() {
  const [schema, setSchema] = useState({
    type: 'object',
    properties: {},
    required: []
  });

  return (
    <JsonSchemaBuilder
      schema={schema}
      onChange={setSchema}
      showMetadata={true}
      showOutput={true}
      className="h-[600px]"
      typeLabels={{
        string: 'Text',
        boolean: 'Yes/No',
        object: 'Form',
        array: 'List',
      }}
      propertyLabel={{
        singular: 'field',
        plural: 'fields'
      }}
    />
  );
}

With Undo/Redo

Since the component is fully controlled, you can implement undo/redo easily:

import { useState } from 'react';
import { JsonSchemaBuilder } from 'json-schema-builder-react';

function App() {
  const [history, setHistory] = useState([{
    type: 'object',
    properties: {},
    required: []
  }]);
  const [currentIndex, setCurrentIndex] = useState(0);

  const currentSchema = history[currentIndex];

  const handleChange = (newSchema) => {
    const newHistory = history.slice(0, currentIndex + 1);
    newHistory.push(newSchema);
    setHistory(newHistory);
    setCurrentIndex(currentIndex + 1);
  };

  const undo = () => {
    if (currentIndex > 0) {
      setCurrentIndex(currentIndex - 1);
    }
  };

  const redo = () => {
    if (currentIndex < history.length - 1) {
      setCurrentIndex(currentIndex + 1);
    }
  };

  return (
    <div>
      <div className="toolbar">
        <button onClick={undo} disabled={currentIndex === 0}>
          Undo
        </button>
        <button onClick={redo} disabled={currentIndex === history.length - 1}>
          Redo
        </button>
      </div>
      
      <JsonSchemaBuilder
        schema={currentSchema}
        onChange={handleChange}
      />
    </div>
  );
}

Editable Property Keys (Advanced)

By default, property keys are immutable after creation to prevent breaking existing references in your codebase. However, you can enable key editing with the keyEditable prop:

import { useState } from 'react';
import { JsonSchemaBuilder } from 'json-schema-builder-react';

function App() {
  const [schema, setSchema] = useState({
    type: 'object',
    properties: {
      user_name: {
        type: 'string',
        title: 'User Name'
      }
    },
    required: []
  });

  return (
    <JsonSchemaBuilder
      schema={schema}
      onChange={setSchema}
      keyEditable={true} // ⚠️ Allows changing keys after creation
    />
  );
}

⚠️ Warning: Enabling keyEditable allows users to change property keys even after they've been created. This can break existing code that references these keys. Use with caution, primarily in development environments or when you have proper migration strategies in place.

Standalone Property Editor

If you only need to edit a single property without the full builder UI, you can use the PropertyEditDialog component:

import { useState } from 'react';
import { PropertyEditDialog } from 'json-schema-builder-react';
import type { PropertyData } from 'json-schema-builder-react';

function PropertyEditor() {
  const [isOpen, setIsOpen] = useState(false);
  const [property, setProperty] = useState<PropertyData>({
    id: '1',
    key: 'username',
    title: 'Username',
    type: 'string',
    required: true,
    minLength: 3,
    maxLength: 50,
  });

  return (
    <>
      <button onClick={() => setIsOpen(true)}>
        Edit Property
      </button>
      
      <PropertyEditDialog
        property={property}
        open={isOpen}
        onOpenChange={setIsOpen}
        onSave={(updated) => {
          setProperty(updated);
          // Save to your backend or state management
          console.log('Updated property:', updated);
        }}
        isNewProperty={false}
        showRegex={true}
        typeLabels={{
          string: 'Text',
          number: 'Number',
          boolean: 'Yes/No'
        }}
      />
    </>
  );
}

API Reference

JsonSchemaBuilder Props

Prop	Type	Default	Description
schema	object	Required	The JSON schema object (controlled)
onChange	(schema: any) => void	Required	Callback when schema changes
showMetadata	boolean	false	Show metadata fields (title, description, version)
showImport	boolean	true	Show import button
showClear	boolean	true	Show clear all button
showOutput	boolean	true	Show JSON output panel
showHeader	boolean	true	Show header with action buttons
showSummary	boolean	false	Show summary at bottom
showRegex	boolean	false	Show regex pattern field for strings
keyEditable	boolean	false	Allow editing property keys after initialization (⚠️ may break references)
className	string	"h-screen"	Custom className for container
typeLabels	TypeLabels	Default labels	Custom labels for property types
propertyLabel	{ singular: string, plural: string }	{ singular: 'property', plural: 'properties' }	Custom labels for properties

PropertyEditDialog Props

Prop	Type	Default	Description
property	PropertyData	Required	The property object to edit
open	boolean	Required	Whether the dialog is open
onOpenChange	(open: boolean) => void	Required	Callback when dialog open state changes
onSave	(property: PropertyData) => void	Required	Callback when property is saved
isArrayItem	boolean	false	Whether this property is an array item
isNewProperty	boolean	false	Whether this is a new property (affects key editing)
propertyLabel	{ singular: string, plural: string }	{ singular: 'Property', plural: 'Properties' }	Custom labels
showRegex	boolean	false	Show regex pattern field for strings
keyEditable	boolean	false	Allow editing property key
typeLabels	TypeLabels	Default labels	Custom labels for property types

Customizing Type Labels

You can customize how property types are displayed to your users:

import { useState } from 'react';
import { JsonSchemaBuilder } from 'json-schema-builder-react';
import type { TypeLabels } from 'json-schema-builder-react';

const customLabels: TypeLabels = {
  string: 'Text',
  number: 'Number',
  integer: 'Whole Number',
  boolean: 'Yes/No',
  object: 'Form',
  array: 'List',
  null: 'Empty'
};

function App() {
  const [schema, setSchema] = useState({
    type: 'object',
    properties: {},
    required: []
  });

  return (
    <JsonSchemaBuilder 
      schema={schema}
      onChange={setSchema}
      typeLabels={customLabels}
    />
  );
}

This affects:

• The type dropdown in the property editor
• Type labels shown in property cards
• Tooltips displaying type information

Available types to customize:

• string - Default: "String"
• number - Default: "Number"
• integer - Default: "Integer"
• boolean - Default: "Boolean"
• object - Default: "Object"
• array - Default: "Array"
• null - Default: "Null"

Available Exports

Component

• JsonSchemaBuilder - Main builder component (controlled)

Types

• JsonSchemaBuilderProps - Props for the main component
• TypeLabels - Type for customizing property type labels

Advanced Usage

Integration with State Management

The controlled component pattern makes it easy to integrate with any state management solution:

Redux

import { useSelector, useDispatch } from 'react-redux';
import { JsonSchemaBuilder } from 'json-schema-builder-react';
import { updateSchema } from './schemaSlice';

function App() {
  const schema = useSelector(state => state.schema);
  const dispatch = useDispatch();

  return (
    <JsonSchemaBuilder
      schema={schema}
      onChange={(newSchema) => dispatch(updateSchema(newSchema))}
    />
  );
}

Zustand

import { useSchemaStore } from './store';
import { JsonSchemaBuilder } from 'json-schema-builder-react';

function App() {
  const { schema, setSchema } = useSchemaStore();

  return (
    <JsonSchemaBuilder
      schema={schema}
      onChange={setSchema}
    />
  );
}

Development

# Install dependencies
npm install

# Run demo app in development mode
npm run dev

# Build the library
npm run build:lib

# Build the demo app
npm run build

# Deploy demo to GitHub Pages
npm run deploy

Troubleshooting

PostCSS Warning

If you see this warning:

A PostCSS plugin did not pass the `from` option to `postcss.parse`

Solution: Make sure you have a postcss.config.js file in your project root:

export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

And verify your tailwind.config.js includes the library path:

module.exports = {
  content: [
    './src/**/*.{js,jsx,ts,tsx}',
    './node_modules/json-schema-builder-react/**/*.{js,jsx}',
  ],
  // ...
};

Styles Not Appearing

Make sure you:

• Have Tailwind CSS installed and configured
• Added the library to your Tailwind content paths (see Styling section)
• Imported Tailwind CSS in your main CSS file

License

MIT © Martin Arusalu

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

• 🐛 Report a bug
• 💡 Request a feature
• 📖 View demo