@sciphergfx/json-fields

UI-agnostic React component for JSON → Form Fields, with support for Chakra UI, Tailwind CSS, and shadcn/ui.

Features

• 🎨 UI Library Agnostic - Works with Chakra UI, Tailwind CSS, shadcn/ui, or plain HTML
• 📝 JSON to Form Fields - Generate form fields from JSON objects
• 🔄 Real-time Updates - Get callbacks on field changes
• 💾 Save/Cancel Actions - Built-in save and cancel functionality
• 🎯 TypeScript Support - Full TypeScript definitions included
• 📱 Responsive - Works on all screen sizes
• 🧩 Sections - Group form fields into collapsible sections
• 🏷️ Array chips - Arrays of strings render as pill chips with add/delete
• 🌓 Per-component light/dark - Switch mode per component (works with Chakra)

Headless Core (Lightweight)

This package now provides a headless core with no UI library dependency. You style via classNames and styles, or override primitives with renderers.

• classNames: slot-to-class mapping, e.g. { container, heading, sectionHeader, fieldLabel, input, textarea, chip, chipClose, button, secondaryButton, list, row, icon, label }.
• styles: per-slot inline styles, same keys as classNames.
• renderers: override primitives like { Container, Box, Button, Input, Select, Textarea, Text, Heading, VStack, HStack, Card, Alert, Label }.

Chakra/shadcn/Tailwind can be used externally by supplying classes or renderers. The previous uiLibrary prop is deprecated for the core path.

Installation

npm install @sciphergfx/json-fields

Peer Dependencies

npm install react react-dom

Optional UI Library Dependencies

For Chakra UI support:

npm install @chakra-ui/react @emotion/react

Quick Start

Fields Component

import { Fields } from '@sciphergfx/json-fields'

const MyForm = () => {
  const handleSave = (nestedData, flatData) => {
    console.log('Form data:', nestedData)
  }

  return (
    <Fields
      uiLibrary="shadcn"
      // Group fields into collapsible sections (optional)
      sections={[
        {
          id: 'profile',
          title: 'Profile',
          description: 'Basic info',
          fields: ['name', 'email', 'website', 'role', 'joinDate'],
          collapsible: true,
          defaultOpen: true,
        },
        {
          id: 'preferences',
          title: 'Preferences',
          fields: ['preferences.theme', 'preferences.notifications', 'isActive'],
          collapsible: true,
          defaultOpen: true,
        },
        {
          id: 'security',
          title: 'Security',
          fields: ['password'],
          collapsible: true,
          defaultOpen: false,
        },
        {
          id: 'about',
          title: 'About',
          fields: ['bio', 'skills', 'tags'],
          collapsible: true,
          defaultOpen: true,
        },
      ]}
      includeUnsectioned
      onSave={handleSave}
      onCancel={() => console.log('Form cancelled')}
      onFieldChange={(key, value, fullData) => {
        console.log(`Field ${key} changed:`, value)
      }}
      initialJson={JSON.stringify({
        user: {
          name: 'John Doe',
          email: '[email protected]',
          preferences: {
            theme: 'dark',
            notifications: true,
          },
        },
        skills: ['React', 'TypeScript'],
        tags: ['dev', 'ui'], // Arrays of strings render as pill chips with add/delete
      })}
      showJsonInput={false} // Hide JSON input, show only form
    />
  )
}

API Reference

Fields Props

Prop	Type	Default	Description
uiLibrary	'chakra' | 'tailwind' | 'shadcn'	'chakra'	UI library to use for styling
onSave	(nestedData, flatData) => void	-	Callback when save button is clicked
onCancel	() => void	-	Callback when cancel button is clicked
onFieldChange	(key, value, fullData) => void	-	Callback when any field changes
saveButtonText	string	'Save Changes'	Text for the save button
cancelButtonText	string	'Reset Form'	Text for the cancel button
initialJson	string	''	Initial JSON string to load
customStyles	object	{}	Custom styles object
showControls	boolean	true	Whether to show save/cancel buttons
showJsonInput	boolean	true	Whether to show JSON input textarea
sections	Array<{ id?, title, description?, fields: string[], collapsible?, defaultOpen? }>	null	Group fields into sections
includeUnsectioned	boolean	false	Show fields not in sections under an "Other" section
unsectionedTitle	string	'Other'	Title for unsectioned fields section

Styling

Tailwind CSS

When using uiLibrary="tailwind", the components output Tailwind utility classes. This package does not bundle Tailwind.

Requirements:

• Tailwind CSS configured in your app (tailwind.config.js, PostCSS, etc.).

Quick setup:

1. Install and configure Tailwind per official docs.
2. Ensure your content globs include your app code using <Fields /> so classes are not purged.
3. Use uiLibrary="tailwind" in <Fields />.

Chakra UI

When using uiLibrary="chakra", the components will use Chakra UI components. Make sure you have Chakra UI set up with your theme provider.

shadcn/ui

When using uiLibrary="shadcn", the components output class names compatible with shadcn/ui. This package does not bundle shadcn/ui or Tailwind.

Requirements:

• Tailwind CSS configured in your app.
• shadcn/ui installed (or compatible design tokens/variables like bg-primary, text-muted-foreground, etc.).

Quick setup:

1. Install Tailwind and shadcn/ui per their docs.
2. Ensure your Tailwind theme exposes the tokens used by shadcn/ui.
3. Use uiLibrary="shadcn" in <Fields />.

Custom Styles

You can override styles using the customStyles prop:

<Fields
  uiLibrary="tailwind"
  customStyles={{
    container: { maxWidth: '800px' },
    input: { borderRadius: '8px' },
    button: { backgroundColor: '#007bff' },
  }}
/>

Utility Functions

The package also exports utility functions for working with JSON:

import {
  flattenObject,
  unflattenObject,
  parseJsonSafely,
  getInputType,
} from '@sciphergfx/json-fields'

// Flatten nested objects
const flat = flattenObject({ user: { name: 'John' } })
// Result: { 'user.name': 'John' }

// Unflatten back to nested
const nested = unflattenObject({ 'user.name': 'John' })
// Result: { user: { name: 'John' } }

// Safe JSON parsing
const result = parseJsonSafely('{"name": "John"}')
// Result: { success: true, data: { name: 'John' } }

TypeScript Support

The package includes full TypeScript definitions:

import { FieldsProps } from '@sciphergfx/json-fields'

const MyComponent: React.FC<FieldsProps> = (props) => {
  // Your component logic
}

Examples

With Custom Styling

<Fields
  uiLibrary="tailwind"
  customStyles={{
    container: { padding: '2rem' },
    formCard: { border: '2px solid #e2e8f0' },
    input: { borderRadius: '8px' },
    button: { backgroundColor: '#3b82f6' },
  }}
  onSave={(data) => console.log('Saved:', data)}
/>

Author

Seyi K. Ogunbowale

License

MIT

Contributing

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