PopKit

Accessible, lightweight popups for WordPress. Native <dialog>, full keyboard and screen reader support, cache-safe targeting, and no jQuery.

PopKit builds popups out of the browser's own <dialog> element and the block editor, rather than out of a framework and a modal library. The result is a frontend bundle under 7 KB gzipped, a keyboard and screen reader experience that behaves the way the platform behaves, and targeting that stays correct behind a page cache.

This README is for people getting PopKit from GitHub: installing a release, building it from source, or contributing to it. If you're looking for the WordPress.org-style plugin description (installation via the Plugins screen, the full FAQ, targeting rules), see readme.txt. It's the same plugin, written for that audience instead of this one.

Why

Most WordPress popup plugins ship a modal framework, hide the trigger and targeting logic behind a paid tier, and treat accessibility as a checkbox. PopKit is built the other way round.

Focus trapping, focus return, Escape-to-close, and a 44×44px close button with no way to turn it off come from <dialog> and this plugin's own runtime, not from an add-on. Every accessibility invariant has a Playwright test backing it; see docs/CLAUDE.md → Hard constraints.

Server-side code never makes a rendering decision that depends on the visitor. Targeting that varies by visitor, such as login state, UTM params, referrer, visit history, or device, is evaluated in the browser against a small config payload, so the same cached HTML is correct for every visitor of a page.

The frontend bundle is budgeted and CI-enforced: 8 KB gzipped for JS, 4 KB for CSS. No jQuery, no bundled UI framework on the frontend.

Two layouts, not a slide-in/sticky-bar/fullscreen-takeover feature matrix. A modal, and a notification bar that can either overlay the page or push it out of the way. Video embeds (YouTube, Vimeo) inside either one are sized to fit, stay at their real aspect ratio, and stop playing when the popup closes.

Extending it is a PHP-only act. Register a condition, its fields and the controls they use, and the block editor sidebar and the classic editor meta boxes both render working UI for it, with no JavaScript build step.

Installing a release

1. Download the latest popkit.zip from Releases, or build one yourself (see Building from source below).
2. In wp-admin: Plugins → Add New → Upload Plugin, choose the zip, then Install Now.
3. Activate it. PopKit checks WordPress and PHP versions on activation and shows an explanatory admin notice instead of a fatal error if either is unmet.
4. Go to Popups → Add Popup.

Requires WordPress 6.5+ and PHP 8.1+.

Building from source

git clone https://github.com/skm16/PopKit.git
cd PopKit
npm install
composer install
npm run build:zip

This produces build/popkit.zip: a single top-level popkit/ directory containing only what ships (no src/, no tests/, no node_modules/), built and verified by tools/build-zip.mjs. Upload that zip the same way as a downloaded release.

npm run build alone (without :zip) compiles dist/frontend.{js,css} and dist/editor.js in place, which is enough to run the plugin directly from a git checkout in wp-content/plugins/ without packaging it.

Contributing

See CONTRIBUTING.md for the development setup, the test suites, and the invariants this codebase enforces mechanically (no regular expressions against authored content, no wall-clock reads on the frontend, cache safety) rather than by convention alone.

Documentation

• readme.txt: the WordPress.org-format plugin description, with the full feature list, FAQ, targeting and trigger reference, and changelog.
• docs/CLAUDE.md: the project's architectural invariants and hard constraints. Written for a contributor (human or AI) who needs to know why something is built the way it is before changing it.
• docs/data-model.md: the stored data shape, including post meta schema, REST payloads, and what's cached and what isn't.

License

Dual-licensed: GPL-2.0-or-later or MIT, at your option. See LICENSE.md.

Author

Sean Roberts