JSKit Fields

JSKit Fields is a flexible, extensible React field/component library for building dynamic, maintainable forms in WordPress plugins and applications. It supports a wide range of field types, grouping, conditional logic, and custom layouts—all with a simple, declarative configuration.

Installation

Install via your preferred package manager:


npm install @wpmvc/fields


pnpm add @wpmvc/fields


yarn add @wpmvc/fields


bun add @wpmvc/fields

Features

Comprehensive field types: Text, number, switch, checkbox, color, select, radio, slider, toggle group, repeater, tabs, group, panel, border, dimension, notice, row, and more.
Composable: Nest fields inside groups, panels, tabs, repeaters, and rows.
Declarative config: Define your form structure with a simple JS object.
Conditional logic: Show/hide fields based on attribute values.
TypeScript support: Strongly typed for safety and autocompletion.

Usage Example

You can use JSKit Fields by passing a fields config and state handlers to the <Fields /> component.

[!TIP] Recommended: Use the useAttributes hook to manage attributes state.


import { Fields, useAttributes } from '@wpmvc/fields';
 
const fields = {
  text: {
    type: 'text',
    label: 'Text Field',
    description: 'A simple text input',
    required: true,
  },
  // ...other fields
};
 
function MyForm() {
  const [attributes, setAttributes] = useAttributes({});
 
  return (
    <Fields
      fields={fields}
      attributes={attributes}
      setAttributes={setAttributes}
    />
  );
}

Registering Custom Components

You can extend or override field types by passing a components prop to <Fields />. This allows you to register your own custom field components or replace existing ones.


import { Fields, useAttributes } from '@wpmvc/fields';
import MyCustomField from './MyCustomField';
 
const fields = {
  custom: {
    type: 'custom',
    label: 'Custom Field',
    description: 'This is a custom field.',
  },
};
 
const components = {
  custom: MyCustomField,
  // You can override built-in types too, e.g. text: MyTextField
};
 
function MyForm() {
  const [attributes, setAttributes] = useAttributes({});
 
  return (
    <Fields
      fields={fields}
      attributes={attributes}
      setAttributes={setAttributes}
      components={components}
    />
  );
}

Using Fields in Gutenberg Block InspectorControls

You can easily use JSKit Fields inside a Gutenberg block’s InspectorControls panel to provide a dynamic, extensible settings UI for your block.


import { InspectorControls } from '@wordpress/block-editor';
import { PanelBody } from '@wordpress/components';
import { Fields, useAttributes } from '@wpmvc/fields';
 
const fields = {
  text: {
    type: 'text',
    label: 'Text Field',
    description: 'A simple text input',
    required: true,
  },
  color: {
    type: 'color',
    label: 'Color Picker',
    description: 'Pick a color',
  },
  // ...add more fields as needed
};
 
export default function Edit({ attributes, setAttributes }) {
  return (
    <>
      <InspectorControls>
          <Fields
            fields={fields}
            attributes={attributes}
            setAttributes={setAttributes}
          />
      </InspectorControls>
      {/* ...your block output... */}
    </>
  );
}

Tips:

Pass your block’s attributes and setAttributes directly to <Fields /> for seamless integration.
You can use all field types and custom components as shown in previous sections.

Field Configuration Examples

Each field type is configured using a simple JavaScript object. You can nest, combine, and customize these fields to create advanced forms.

Text

A single-line text input.


{
  type: 'text',
  label: 'Text Field',
  description: 'A simple text input',
  required: true,
}

Number

A numeric input with optional min, max, and step.


{
  type: 'number',
  label: 'Number Field',
  min: 0,
  max: 100,
  description: 'A number input',
}

Switch

A boolean toggle switch.


{
  type: 'switch',
  label: 'Switch Field',
  description: 'A toggle switch',
}

Checkbox

A single checkbox input.


{
  type: 'checkbox',
  label: 'Checkbox Field',
  description: 'A single checkbox',
}

Tabs

Tabbed navigation for grouping fields.


{
  type: 'tabs',
  label: 'Tabs Field',
  items: {
    tab1: { label: 'Tab 1', fields: {} },
    tab2: {
      label: 'Tab 2',
      fields: {
        tab1: { type: 'text', label: 'Tab 1 Content' },
        tab2: { type: 'number', label: 'Tab 2 Content' },
      },
    },
  },
}

Color

A color picker input.


{
  type: 'color',
  label: 'Color Picker',
  description: 'Pick a color',
}

Colors

A palette or group of color pickers.


{
  type: 'colors',
  label: 'Color Palette',
  items: {
    color: {
      label: 'Color',
      showByDefault: true,
      colors: {
        default: { label: 'Default' },
        hover: { label: 'Hover' },
      },
    },
    background: {
      label: 'Background',
      showByDefault: false,
      colors: {
        default: { label: 'Default' },
        hover: { label: 'Hover' },
      },
    },
  },
  description: 'Choose from palette',
}

Group

Group multiple fields together.


{
  type: 'group',
  label: 'Group Field',
  fields: {
    groupText: { type: 'text', label: 'Group Text' },
    groupNumber: { type: 'number', label: 'Group Number' },
  },
}

Border

Border settings input.


{
  type: 'border',
  label: 'Border Field',
  description: 'Set border properties',
}

Dimension

Input for width, height, or other dimensions.


{
  type: 'dimension',
  label: 'Dimension Field',
  description: 'Set width and height',
}

Notice

Display an informational, warning, or error notice.


{
  type: 'notice',
  notice: 'This is an info notice.',
  status: 'info', // can be 'info', 'warning', 'error', etc.
}

Panel

A collapsible panel for grouping fields.


{
  type: 'panel',
  label: 'Panel Field',
  fields: {
    panelText: { type: 'text', label: 'Panel Text' },
    panelSwitch: { type: 'switch', label: 'Panel Switch' },
  },
}

Radio

A group of radio buttons.


{
  type: 'radio',
  label: 'Radio Field',
  options: [
    { label: 'Radio 1', value: '1' },
    { label: 'Radio 2', value: '2' },
  ],
  description: 'Choose one',
}

Select

A dropdown select input.


{
  type: 'select',
  label: 'Select Field',
  options: [
    { label: 'Select 1', value: '1' },
    { label: 'Select 2', value: '2' },
  ],
  description: 'Select an option',
}

Slider

A range slider input.


{
  type: 'slider',
  label: 'Slider Field',
  min: 0,
  max: 10,
  description: 'Slide to choose',
}

Toggle Group

A group of toggle buttons.


{
  type: 'toggleGroup',
  label: 'Toggle Group Field',
  options: [
    { label: 'A', value: 'a' },
    { label: 'B', value: 'b' },
    { label: 'C', value: 'c' },
  ],
  description: 'Toggle between options',
}

Repeater

Repeatable group of fields.


{
  type: 'repeater',
  label: 'Repeater Field',
  fields: {
    repeaterText: { type: 'text', label: 'Repeater Text' },
    repeaterNumber: { type: 'number', label: 'Repeater Number' },
  },
  description: 'Add multiple items',
}

Row

Layout fields in a row.


{
  type: 'row',
  label: 'Row Field',
  fields: {
    rowText: { type: 'text', label: 'Row Text' },
    rowSwitch: { type: 'number', label: 'Row Number' },
  },
}

Tips & Best Practices

Nesting: You can nest fields inside group, panel, tabs, repeater, and row for advanced layouts.
Conditional Logic: Add a condition function to any field to control its visibility based on current attributes.
Custom Components: Pass a components prop to <Fields /> to override or extend field types.
TypeScript: All field configs are fully typed for safety and autocompletion.

Contributing

Contributions are welcome! Please open an issue or submit a pull request if you’d like to contribute to the project.