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 @shamim-ahmed/fields
# or
yarn add @shamim-ahmed/fields
# or
pnpm add @shamim-ahmed/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.

Field Types Overview

Below is a quick reference table of all available field types. Click any field type to jump to its configuration and usage example.

| Field Type | Description | Example Section | |---------------|---------------------------|----------------------| | text | Single line text input | Text | | number | Numeric input | Number | | switch | Toggle switch | Switch | | checkbox | Checkbox input | Checkbox| | tabs | Tabbed field groups | Tabs | | color | Color picker | Color | | colors | Color palette/group | Colors | | group | Grouped fields | Group | | border | Border settings | Border | | dimension | Dimension input | Dimension| | notice | Info/warning/error notice | Notice | | panel | Collapsible panel group | Panel | | radio | Radio button group | Radio | | select | Dropdown select | Select | | slider | Range slider | Slider | | toggleGroup | Toggle button group | Toggle Group| | repeater | Repeatable field group | Repeater| | row | Row layout for fields | Row |

Usage Example

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

Recommended: Use the useAttributes hook to manage attributes state.

import { Fields, useAttributes } from '@shamim-ahmed/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 '@shamim-ahmed/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 '@shamim-ahmed/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.

License

MIT