@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

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

Quick Start

$3

`tsx
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 }) => (
type={type}
value={value || ''}
onChange={(e) => onChange(e.target.value)}
placeholder={placeholder}
disabled={disabled}
className={className}
{...props}
/>
),

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

// Optional components
Select: ({ value, onChange, options, placeholder, disabled, className }) => (





{options.map((opt) => (

{opt.label}

))}


),

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

// Layout components
VerticalLayout: ({ children, className }) => (


RequiredIndicator: ({ className }) => (
*
),
};
`

$3

`tsx
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

`tsx
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 (

schema={schema}
data={data}
renderers={renderers}
onChange={({ data }) => setData(data || {})}
/>

);
}
`

Component Contracts

Each component type has a defined prop interface:

$3

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

$3

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

$3

`typescript
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

`tsx
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 (
// ...
i18n={i18n}
/>
);
}
`

Custom Testers

Override default tester ranks or add custom testers:

`tsx
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

$3

Creates JSON Forms renderer registry entries.

$3

Creates a JSON Forms i18n configuration object.

$3

React context provider for component map and class names.

$3

- 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