If you've built a Craft plugin, you've probably had a settings page that was going along fine in Twig until it needed one slightly fancier control. A searchable select, say, or a date picker. Then you're choosing between Craft's own jQuery-based Garnish and setting up a whole React build for one dropdown.
Plugin Kit 2 (opens new window) is our answer to that. Plugin Kit started as a React library, but most plugin settings pages are still plain Twig, and they deserve nice controls too. So for version 2, we rebuilt the controls as web components, which work in Twig, Vue or React without changing how they look or behave.
Built Into Eleven Plugins
Plugin Kit is now behind interfaces across Formie, Hyper, Navigation, Control Panel Nav, Metrix, Video Picker, Icon Picker, Table Maker, Timber, Comments and Vizy.
A form builder, a navigation editor and a field settings screen do very different jobs, but they all need menus, inputs, dialogs and validation that behave. Building those once means a fix to a focus ring or a tweak to the date picker happens in one place, and every plugin picks it up when it updates Plugin Kit.
It also means every part of the library is used in screens we build and support ourselves. As more plugins use it, we're finding which pieces belong in the shared toolkit and which need to stay with the plugin.
Choose React, Vue or Twig
The biggest change in version 2 is how the components are built. Their behaviour and styles now come from @verbb/plugin-kit-web, a library of web components built with Lit (opens new window). The React and Vue packages are thin wrappers over those same elements rather than separate implementations, so there's one dropdown to get right instead of three.
For plugin authors, that means three ways in:
- Twig and plain JavaScript, rendering
<pk-*>elements in your templates and loading the components the page needs. - React, using components such as
<Button>through@verbb/plugin-kit-react. - Vue, using the matching components through
@verbb/plugin-kit-vue.
Pick whichever suits the screen. A small settings page can stay in Twig while a bigger app uses React or Vue, and they all get the same keyboard interactions and accessibility behaviour underneath.
If you'd rather skip the frontend build entirely, there's a script-tag loader (opens new window). Host the supplied files in your plugin, and the loader finds the components on the page and loads them as needed.
Controls That Look and Work Like Craft's
The aim is still to follow Craft's control panel patterns wherever they exist, so an editor knows how to use a plugin's settings screen even when there's a fairly involved interface behind it.
Plugin Kit has the everyday controls you'd expect, like buttons, inputs, lightswitches, selects, tabs and tooltips, along with searchable comboboxes, dialogs, date pickers, editable tables, and rich text and code editors. The bigger ones are where sharing saves the most work. Keyboard handling, focus management and putting validation errors next to the right field all take time to get right, and every plugin needs them.
Every component also renders inside its own shadow DOM. If you've ever tried Tailwind in a plugin screen, you'll have met Craft's own flex class and plenty of control panel CSS that was never written with your app in mind, and the shadow DOM keeps all of that out of your controls. You can mount a whole app inside a shadow root too, when it needs the same isolation. The framework providers handle translations and portals for floating menus, and optional host helpers connect your app to Craft's actions and selectors. The React (opens new window) and Vue (opens new window) quick starts walk through loading an interface on a Craft control panel page.
Import What Your Screen Needs
You can load individual component families, so a page with one button doesn't import the rich text editor alongside it. With a frontend build, a button-only entry can be as small as this.
import '@verbb/plugin-kit-web/plugin-kit.css';
import '@verbb/plugin-kit-web/components/button.js';Once Craft loads that entry and its stylesheet through your asset bundle, your Twig template can contain the following.
<pk-button variant="primary">{{ 'Save'|t('app') }}</pk-button>The web component quick start (opens new window) covers the build and asset bundle setup around it. TipTap and CodeMirror have their own shared packages, and icons are registered explicitly, so you import only the families and glyphs you use. The full registration entry is there for when you really do want the whole library.
Describe Your Settings With SchemaForm
Once a settings screen grows conditional fields, validation and server errors, SchemaForm (opens new window) lets you describe those fields as data. If you've used Craft's Twig form macros, it'll feel familiar. Describe the field and let the shared controls handle how it looks. In PHP, that might be:
$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',
],
];Pass the schema and values to your frontend, and SchemaForm renders the fields and keeps track of the form state. In version 2 the shared engine lives in @verbb/plugin-kit-forms, with React and Vue providing the UI bindings, so the same schema works with either.
Plugin-specific fields still fit in. Formie's variable picker uses Formie's own data and rules while taking part in the same form, and those details stay with Formie. The settings screen recipe (opens new window) walks through the whole thing, from passing a schema from PHP to rendering it in React, saving values and showing errors returned by Craft.
Upgrading From Version 1
On the off chance you'd already taken Plugin Kit 1 for a spin, version 2 has breaking changes, starting with the Base UI components being replaced by the web component wrappers. Have a look through the 2.0.0 changelog (opens new window) before updating.
Getting Started
We built Plugin Kit for our own plugins, and it's here for yours too. It's free and open source under the MIT licence. The docs (opens new window) have Web, React and Vue quick starts, the packages are on npm starting with Plugin Kit Web (opens new window), and the source is on GitHub (opens new window). If something doesn't behave, open an issue (opens new window) and let us know.