Plugin Kit

Verbb Team Verbb Team June 2026 7 min read

Blog plugin kit

Heads up! Plugin Kit 2 is out now, with Web Component, Vue and React support. Check out the announcement for more.

We've been building more of our Craft plugin control panel screens with React lately. Metrix was our first plugin built with React, and it went well enough that when Formie 4's builder needed a rebuild, React was the obvious choice. They won't be the last, either.

Keeping all the useful bits locked inside one plugin didn't make much sense, so we've pulled them out into a standalone package, @verbb/plugin-kit-react (opens new window). It's for Craft plugin developers who want richer control panel screens without solving the same setup, styling, form and Craft integration problems every single time.

Why We Built It

The Craft control panel is great at a lot of things, but once a plugin screen gets more interactive, the old mix of Twig, jQuery, one-off JavaScript and a few prayers starts to show its age.

Craft's own JavaScript framework, Garnish, has carried a lot of control panel behaviour for a long time. For plugin developers today, though, it's a tough foundation to build on. It's jQuery-based, largely undocumented, and gets pretty cumbersome once you're building something app-like.

For small settings pages, server-rendered HTML is still perfectly fine, and we're not suggesting every plugin needs to become a tiny SPA because one dropdown got ambitious. For complex forms, searchable pickers, drag-and-drop, rich text, conditional settings, previews and builder-style screens, though, React gives us a much better foundation.

You might be wondering whether React is an odd bet when Craft 6 (opens new window) is starting to point towards a Vue and Inertia-based control panel. It's exciting to see, but Craft 6 is still in early alpha, so we're not touching that — yet! Plugin Kit React is about giving Craft 5 plugin developers a practical path right now, and we'll revisit Craft 6 once there's a firmer target to build against.

Getting React onto the page is the easy bit. The work is in making it feel like it belongs inside Craft, which for us came down to a handful of things.

  • Translations still work.
  • Dialogs and popovers mount in the right place.
  • Controls look and behave like Craft's own.
  • Forms handle validation and server errors cleanly.
  • Styling works in the normal DOM or a Shadow DOM.
  • Plugins don't need to rebuild the same build and host integration pieces each time.

What's in the Package

Under the hood, it's built on tools we already like working with. Base UI (opens new window) provides accessible headless primitives, Tailwind CSS (opens new window) v4 handles styling, Valibot (opens new window) does schema validation and Zustand (opens new window) holds form state. Rich text runs on Tiptap (opens new window) and ProseMirror (opens new window), with Framer Motion (opens new window) and dnd kit (opens new window) filling in animation and drag-and-drop.

On top of those, you get React components that fit the control panel, form primitives and schema-driven form tools, hooks for translations, dialogs and portals, helpers for wiring an app into Craft, and a stylesheet at @verbb/plugin-kit-react/style.css. The smaller @verbb/plugin-kit utility package comes along with it, so most projects only need to install the React package (and React itself).

npm install @verbb/plugin-kit-react react react-dom
Plugin kit react cp app
A React screen running inside the Craft control panel, using Plugin Kit React's components and styles.

Components That Match Craft's Control Panel

Every plugin author building a React screen ends up making the same choices about sizing, spacing, focus states, menus, popovers and form controls. Plugin Kit React makes them once, in a way that suits a Craft plugin.

We're not creating a whole separate design system for Craft, either. The aim is to follow Craft's control panel patterns wherever they already exist, and only go further where a plugin needs a richer component that Craft doesn't really provide. Ideally, people notice the plugin is nicer to use and never wonder whether it came from a different planet.

The package covers the common building blocks, like buttons, inputs, textareas, selects, comboboxes, checkboxes, lightswitches, dialogs, dropdown menus, tabs, tooltips, calendars, date pickers, tables and scroll areas.

Plugin kit react components
From everyday form controls through to searchable comboboxes and floating menus.

Schema-Driven Forms

For more complex settings screens, there's SchemaForm. A plugin describes its form as structured data and passes it to React, and SchemaForm renders the fields, tracks values, runs validation, handles conditions and submits the final payload.

If you've built Craft plugin settings screens before, the idea will feel familiar. Craft has long provided Twig form macros (opens new window) like forms.textField(), backed by field templates such as field.twig (opens new window) and text.twig (opens new window), so you've probably written something like this.

{{ forms.textField({
    label: 'Name' | t('app'),
    instructions: 'What this section will be called in the control panel.' | t('app'),
    id: 'name',
    name: 'name',
    value: section.name,
    errors: section.getErrors('name'),
    required: true,
}) }}

SchemaForm aims for a similar developer experience on React-powered screens. Your PHP still describes the field, with its translated label, defaults, validation rules and errors, and React takes care of rendering and interaction.

$schema = [
    [
        '$field' => 'text',
        'name' => 'name',
        'label' => Craft::t('app', 'Name'),
        'instructions' => Craft::t('app', 'What this section will be called in the control panel.'),
        'required' => true,
        'validation' => 'required',
    ],
];

$formConfig = [
    'schema' => $schema,
    'values' => [
        'name' => $section->name,
    ],
    'errors' => [
        'name' => $section->getErrors('name'),
    ],
];

The same approach covers lightswitches, selects and comboboxes, date and time fields, editable tables, rich text and variable pickers, and grouped or conditional sections. It's been especially handy for screens where the UI is data-driven, repeatable or configurable. Which, as it turns out, is a lot of plugin screens.

Plugin kit react schema form docs
No hand-written form markup was harmed in the making of this screen.

Mounting Inside the Control Panel

A React app will happily render into any DOM node, but Craft plugin screens also need to talk to Craft's browser environment, send action requests, use translations, open dialogs, put floating UI in the right place and sometimes render inside a Shadow DOM. A small setup step tells Plugin Kit React how to behave on your plugin's page.

import { createRoot } from 'react-dom/client';
import '@verbb/plugin-kit-react/style.css';

import { App } from './App';
import { configurePluginKitReact, createCraftHostBridge } from '@verbb/plugin-kit-react/utils';

configurePluginKitReact({
  hostBridge: createCraftHostBridge(),
  translationCategory: 'my-plugin',
});

const container = document.getElementById('my-plugin-root');

if (container) {
  createRoot(container).render(<App />);
}

React still renders your UI, and Plugin Kit React handles fitting it into the Craft page around it.

Shadow DOM Support

Control panel CSS gets complicated quickly once a plugin screen gets bigger, so Plugin Kit React supports both regular DOM rendering and Shadow DOM rendering. Use the normal setup when your screen should blend straight into the page, and Shadow DOM when you want a more self-contained app with tighter control over styles.

If you haven't used it before, a Shadow DOM is a self-contained part of the page that your app renders into. It's still part of the control panel, but its markup and styles are kept apart from the rest of the page, so your app is less likely to pick up Craft's styling or leak its own back out.

Say you want to use Tailwind in your plugin's screen. On a normal Craft page, that gets messy fast. Craft has its own classes like flex, already includes a version of Tailwind's reset styles, and has plenty of control panel CSS that was never written with your React app in mind. Inside a Shadow DOM, a utility framework, design system or custom reset becomes much easier to work with.

Formie 4 Is the First Big User

Formie 4 is where we've used it most. Its new builder, richer control panel interactions, variable picker, schema-driven settings and frontend tooling all pushed us to make the shared layer reusable, so instead of keeping it inside Formie, we pulled the general pieces out for other plugins to use.

Getting Started

The Plugin Kit React docs (opens new window) walk through adding a React-powered screen to an existing Craft plugin, from the frontend folder and Vite setup to the Craft asset bundle, the mount element and your first component. Once it's installed, import the styles and whatever components, hooks and utilities you need.

import { Button } from '@verbb/plugin-kit-react/components';
import { useTranslation } from '@verbb/plugin-kit-react/hooks';
import { cn } from '@verbb/plugin-kit-react/utils';
import '@verbb/plugin-kit-react/style.css';

You can start small with a single screen, or go further with SchemaForm and the app integration helpers.

Give It a Crack

Plugin Kit React is available now on npm (opens new window). We're using it ourselves, and we'll keep improving it as more Verbb plugins move onto the same foundation. If you've been wanting a cleaner way to bring React into the control panel, we'd love you to try it, and to hear about anything weird through our contact page or GitHub (opens new window).

And who knows, if enough Craft plugin developers want the same sort of thing for Vue one day, we might just have to see what happens there too.