@apart-tech/jsonforms-kit

A headless, bring-your-own-components library for rendering JSON Forms with any React component library. The library handles all the heavy lifting (renderer registration, tester logic, layout dispatching, i18n integration, conditional visibility) while allowing consumers to provide their own UI components.

Features

• Headless: No CSS or styling dependencies - bring your own components
• Type-safe: Full TypeScript support with component contracts
• Flexible: Works with shadcn/ui, MUI, Chakra UI, or any component library
• Comprehensive: Supports all common form controls out of the box
• Extensible: Easy to add custom controls and testers

Installation

npm install @apart-tech/jsonforms-kit @jsonforms/core @jsonforms/react

Quick Start

1. Create your component map

import { Input } from '@/components/ui/input';
import { Label } from '@/components/ui/label';
import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '@/components/ui/select';
import { Checkbox } from '@/components/ui/checkbox';

const componentMap = {
  // Required components
  Input: ({ value, onChange, type, placeholder, disabled, className, ...props }) => (
    <Input
      type={type}
      value={value || ''}
      onChange={(e) => onChange(e.target.value)}
      placeholder={placeholder}
      disabled={disabled}
      className={className}
      {...props}
    />
  ),

  Label: ({ children, className, htmlFor }) => (
    <Label className={className} htmlFor={htmlFor}>{children}</Label>
  ),

  // Optional components
  Select: ({ value, onChange, options, placeholder, disabled, className }) => (
    <Select value={value} onValueChange={onChange} disabled={disabled}>
      <SelectTrigger className={className}>
        <SelectValue placeholder={placeholder} />
      </SelectTrigger>
      <SelectContent>
        {options.map((opt) => (
          <SelectItem key={opt.value} value={opt.value}>
            {opt.label}
          </SelectItem>
        ))}
      </SelectContent>
    </Select>
  ),

  Checkbox: ({ checked, onChange, disabled, className }) => (
    <Checkbox
      checked={checked}
      onCheckedChange={onChange}
      disabled={disabled}
      className={className}
    />
  ),

  // Layout components
  VerticalLayout: ({ children, className }) => (
    <div className={className || 'space-y-6'}>{children}</div>
  ),

  HorizontalLayout: ({ children, className }) => (
    <div className={className || 'flex gap-4 items-end'}>{children}</div>
  ),

  Group: ({ label, children, className }) => (
    <fieldset className={className || 'space-y-4 border rounded-lg p-4'}>
      {label && <legend className="text-lg font-semibold">{label}</legend>}
      {children}
    </fieldset>
  ),

  // Error display
  ErrorMessage: ({ message, className }) => (
    <p className={className || 'text-sm text-red-600 mt-1'}>{message}</p>
  ),

  RequiredIndicator: ({ className }) => (
    <span className={className || 'text-red-500 ml-1'}>*</span>
  ),
};

2. Create renderers

import { createRenderers } from '@apart-tech/jsonforms-kit';

const renderers = createRenderers({
  components: componentMap,
  classNames: {
    field: 'space-y-1',
    label: 'text-sm font-medium',
    error: 'text-sm text-red-600 mt-1',
    required: 'text-red-500 ml-1',
    layouts: {
      vertical: 'space-y-6',
      horizontal: 'flex gap-4 items-end',
      group: 'border rounded-lg p-4',
    },
  },
});

3. Use with JsonForms

import { useState } from 'react';
import { JsonForms } from '@jsonforms/react';
import { FormProvider } from '@apart-tech/jsonforms-kit';

function MyForm() {
  const [data, setData] = useState({});

  const schema = {
    type: 'object',
    properties: {
      name: { type: 'string', title: 'Name' },
      email: { type: 'string', format: 'email', title: 'Email' },
      role: {
        type: 'string',
        title: 'Role',
        enum: ['admin', 'user', 'guest'],
      },
    },
    required: ['name', 'email'],
  };

  return (
    <FormProvider components={componentMap}>
      <JsonForms
        schema={schema}
        data={data}
        renderers={renderers}
        onChange={({ data }) => setData(data || {})}
      />
    </FormProvider>
  );
}

Component Contracts

Each component type has a defined prop interface:

Input

interface InputProps {
  value: string;
  onChange: (value: string) => void;
  disabled?: boolean;
  placeholder?: string;
  type?: 'text' | 'email' | 'password' | 'tel' | 'url' | 'number';
  className?: string;
}

Select

interface SelectProps {
  value: string;
  onChange: (value: string) => void;
  options: Array<{ value: string; label: string }>;
  placeholder?: string;
  disabled?: boolean;
  className?: string;
}

Checkbox

interface CheckboxProps {
  checked: boolean;
  onChange: (checked: boolean) => void;
  disabled?: boolean;
  className?: string;
}

See the types documentation for all component contracts.

Supported Controls

| Control | Schema Match | Component | |---------|--------------|-----------| | String | type: "string" | Input | | Email | format: "email" | Input (type="email") | | Password | format: "password" | Input (type="password") | | URL | format: "uri" | Input (type="url") | | Phone | format: "phone" or scope ends with phone | Input (type="tel") | | Number | type: "number" or type: "integer" | Input (type="number") | | Boolean | type: "boolean" | Checkbox | | Toggle | type: "boolean" + options.format: "toggle" | Toggle | | Select | enum or oneOf | Select | | Radio | enum/boolean + options.format: "radio" | RadioGroup | | Combobox | enum + options.format: "combobox" | Combobox | | Date | format: "date" | DatePicker | | DateTime | format: "date-time" | DateTimePicker | | Textarea | string + options.multi: true | Textarea | | Slider | number + options.format: "slider" | Slider | | Currency | format: "currency" | Input (with formatting) | | File | format: "file" or contentMediaType | FileUpload |

i18n Support

import { createI18n } from '@apart-tech/jsonforms-kit';
import { useTranslations } from 'next-intl';

function useFormI18n(namespace: string) {
  const t = useTranslations(namespace);
  const tErrors = useTranslations('formErrors');

  return createI18n({
    translate: (key, defaultValue) => {
      const translated = t(key);
      return translated !== key ? translated : defaultValue;
    },
    translateError: (error) => {
      const translated = tErrors(error.keyword);
      return translated !== error.keyword ? translated : error.message;
    },
    locale: 'en',
  });
}

// Usage
function MyForm() {
  const i18n = useFormI18n('forms.personalInfo');

  return (
    <JsonForms
      // ...
      i18n={i18n}
    />
  );
}

Custom Testers

Override default tester ranks or add custom testers:

import { createRenderers, rankWith, scopeEndsWith } from '@apart-tech/jsonforms-kit';

const renderers = createRenderers({
  components: componentMap,
  testers: {
    // Override default ranks
    ranks: {
      email: 10, // Higher priority for email fields
      select: 4,
    },
    // Add custom testers
    custom: [
      {
        name: 'specialPhone',
        tester: rankWith(10, scopeEndsWith('mobileNumber')),
        renderer: 'Input',
        props: { type: 'tel' },
      },
    ],
  },
});

API Reference

createRenderers(config)

Creates JSON Forms renderer registry entries.

createI18n(config)

Creates a JSON Forms i18n configuration object.

FormProvider

React context provider for component map and class names.

Hooks

• useComponents() - Access the component map
• useClassNames() - Access class name configuration
• useFieldWrapper(props) - Common field wrapper logic
• useHasComponent(name) - Check if a component is available

License

MIT