Build and manage popups
Create reusable popups and control their content, layout, triggers, audience, and behavior.
Watch the video
Chapters and transcript Captions are included.
How Kindly popups work, for the people and agents building with them. Every setting, with its values and default, is in POPUP-SETTINGS.md and popup-settings.schema.json. Both are generated from the code. Read this page first, then look settings up there.
Source: includes/popups.php (settings table, validation, loading, REST), templates/popup.php (the editing stage), assets/popup-settings.js (the settings panel), the popup section of assets/elements.js (what visitors' browsers run) and of assets/elements.css.
The one rule: settings only#
A popup is built from its settings and ordinary Kindly content. There is nothing else.
- Use the settings that exist. Every option is in the table. A key that isn't in it is refused by name when the popup is saved, never silently dropped.
- Don't write scripts or styles to open, close, place, animate or limit popups. Each of those already has a setting, a link, an element setting or a public API call. If a requirement truly can't be met, say so and name the closest setting. Don't build a workaround.
- The content inside the box is normal Kindly content (headings, text, buttons, forms, images, grids), edited and styled like any page. The same build standard applies: BUILD-STANDARD.md.
- Don't edit
docs/POPUP-SETTINGS.mdordocs/popup-settings.schema.jsonby hand. Changecantata_edit_popup_schema()and runwp eval-file bin/popup-docs.php.tests/popups-full-test.phpfails while they are out of date.
What a popup is#
- A post of type
kindly_popup. People who can manage templates create and edit it in Page options > Popups. It has no public address of its own: it shows only on pages. - Its content is one box,
<div class="ke-popup-box" data-ke-popup='{...}'>. Everything visitors see is inside the box. The box'sdata-ke-popupattribute holds the settings JSON. Saving content outside the box, or a second box, is refused. - The JSON has five parts:
layout: size, position, per-screen-size overrides, the overlay, the close button and animation.behavior: how it closes, opening by hand, forms inside it, snoozing, focus and tracking.where: which pages load it automatically, and which never get it.when: the triggers that open it automatically.rules: who sees it, how often, where they came from, and its schedule.
- Anything left out takes its default, so
{}is a valid popup: a 640px modal in the middle that loads nowhere and opens only by hand. - Draft and publish work as they do for pages. Visitors only ever get the published version.
Kinds#
A new popup starts from a kind. A kind only sets the starting layout; after that it's ordinary settings that can be changed freely.
| Kind | Starts as |
|---|---|
| Modal | The defaults: centered, 640px, with an overlay |
| Slide-in | 380px at the bottom right with no overlay, full width on phones |
| Bar at the top | Full width, flush with the top, no overlay |
| Bar at the bottom | Full width, flush with the bottom, no overlay |
| Full screen | Covers the screen |
| Side panel, left or right | A full-height panel on that side, 88vw wide on phones |
The exact values are in the Kinds table of POPUP-SETTINGS.md.
The Popups screen#
Since 0.9.17, Kindly Edit > Popups in WordPress lists every popup in one table: a small drawing of it, its name and kind, where it shows, what opens it, its views and conversions over the last 30 days, and its status. Use the search box and the status filter (On, Off, Draft) to narrow the list; the count under it says how many match, and Clear shows them all again.
- The video button beside the title plays the Site popups video in a window over the screen (0.9.21 and later), from this guide, so it is always the current recording.
- Add popup sits in the list's header; before there are any popups, Add a popup under the empty list takes its place (0.9.19 and later). It opens a focused window: type a name, choose a kind from the drawings, then Create and edit. Esc, Close or Cancel leave without making anything.
- The switch in Status turns a published popup off (no page gets it, its content and settings are kept) or on again. A popup with unpublished changes is turned on by publishing it in the editor.
- Edit, the name and the drawing open the popup in the editor. Duplicate makes a draft copy, and Move to the Trash asks first. The Trash section at the end restores a popup as a draft.
On phones, each popup becomes a stacked row with its column names beside the values.
Since 0.9.17, in the editor's Developer mode, a popup's settings start with where it sits, then When it opens, Where it loads, Who sees it, How often and Schedule. Its overlay, close button, animation and Advanced settings follow.
Getting a popup onto a page#
A page gets a popup in two ways:
Where it loads (
where.include). The popup loads on matching pages and can open by itself through itswhentriggers. Rule types cover:- every page, the front page and the posts page
- single pages of a post type, and chosen posts or pages
- children and descendants of a page
- categories and tags (optionally including child terms), and authors
- a post type's archive, any archive, and date archives
- search results and the not-found page
- a page template file, and words in the address
Brought along. A page that refers to a popup loads it for opening by hand, with no rule needed. A reference is any of these:
- a link to it, on the page or in a menu (classic menus and Navigation blocks)
- an element with Advanced > Popup
- a link inside another popup that is loaded, a few levels deep
- anything else rendered on the page: theme templates, global elements, blocks, block and text widgets, shortcodes
A popup brought along this way opens only when someone uses the link or element. Its automatic triggers don't run unless a
whererule also matches.
where.exclude always wins. A page matching an exclude rule doesn't get the popup by a rule or by being brought along, and a link to the popup there stays an ordinary link. The one exception is a form whose action opens the popup: that choice is explicit, so the form's page always gets it. A popup whose schedule has ended loads nowhere, forms included.
Opening it#
By itself (when)#
Each trigger type can be added once, up to 10 in total. Any one of them opens the popup. It opens at most once per page, and only while rules allow it.
| Trigger | Opens it |
|---|---|
load |
Some seconds after the page loads |
scroll |
Scrolling down past a percentage of the page, or scrolling back up |
scrollTo |
An element coming into view |
hover |
The pointer resting on an element |
clicks |
After a number of clicks on the page |
idle |
After a time without activity |
time |
After time spent on the site during this visit |
exit |
The pointer leaving the top of the window. On phones and tablets, optionally a quick scroll up |
return |
The visitor coming back to the tab after being away |
adblock |
The browser blocks ads |
By hand#
These open the popup whatever its rules say. They need the popup to be on the page, and a link or element trigger brings it along.
Links. Any link in Kindly can point at a popup. In the editor, choose Link to > Popup, pick the popup and what the link does. The link's address is one of:
| Address | Does |
|---|---|
#kindly-popup-ID |
Opens it |
#kindly-popup-ID-toggle |
Opens it, or closes it when it is open |
#kindly-popup-ID-close |
Closes it, from anywhere |
#kindly-popup-close |
Inside a popup: closes the popup it's in |
#kindly-popup-close-never |
Inside a popup: closes it, and it doesn't open by itself again for that visitor |
These work in menus, buttons, text links and image links, and inside other popups to chain them.
Any element (Advanced > Popup in the editor). This is for elements that aren't links, or for opening on hover. The setting is three attributes, which the build contract checks:
| Attribute | Values |
|---|---|
data-ke-popup-open |
The popup's ID. Required when either of the others is present |
data-ke-popup-on |
click (the default) or hover. On hover, a click or Enter still works for keyboards and touch screens |
data-ke-popup-act |
open (the default), toggle or close |
An element that isn't a link or button becomes a keyboard-operable button.
A selector (behavior.selector). A click on anything matching this CSS selector opens the popup. This suits markup you don't control, such as a menu item's class. Prefer a link or Advanced > Popup when you can.
A form. A Kindly form's "after sending" action can open a popup. Its value is the popup's element ID, kindly-popup-ID. A form inside a popup can close it after sending (behavior.submitClose, in seconds; -1 leaves it open), and behavior.afterSubmit controls whether it opens by itself again for that visitor.
JavaScript, for a site's own Custom JavaScript only, never instead of a setting:
KindlyPopups.open(12); // true if popup 12 is on this page
KindlyPopups.close(12); // close(12, true): and not automatically again for this visitor
KindlyPopups.close(); // the popup on top
KindlyPopups.toggle(12);
KindlyPopups.isOpen(12);
KindlyPopups.list(); // [{ id: 12, open: false }, ...]
Closing it#
- The close button (
layout.close): inside the box, outside it, or none. You can set which corner it sits in, a delay before it appears, its size, and its colors at rest and on hover. - Esc (
behavior.escCloses) and a click on the overlay (behavior.overlayCloses). - By itself after some seconds (
behavior.autoClose). - A link inside to
#kindly-popup-closeor#kindly-popup-close-never, and any link inside ifbehavior.linkClosesis on. - After a form inside is sent (
behavior.submitClose). - Opening another popup closes it if
behavior.closeOthersis on.
A popup that visitors can't close is refused. It needs at least one of these: a close button, Esc, a click on the overlay, or closing by itself.
Who sees it and how often (rules)#
The rules apply to automatic opening only. All set rules must pass.
- Visits:
- after a number of page views (
views) or sessions (sessions) - new or returning visitors (
visitor)
- after a number of page views (
- Frequency:
- at most
timesopeningspervisit, day, week, month or ever - snoozed for some hours or days after closing or opening (
behavior.snooze,snoozeFrom,snoozeUnit)
- at most
- Where they came from (
from):- search engines, social sites, AI assistants, other sites, this site, or a referrer containing given words (
fromUrl) fromNotinverts it
- search engines, social sites, AI assistants, other sites, this site, or a referrer containing given words (
- The address and browser:
- address parameters (
query, such asutm_source=newsor justpromo) - a cookie being present or absent (
cookie,cookieHas)
- address parameters (
- Other popups: seen, closed or converted, or not, for up to 5 (
popups, as"ID:seen"and so on) - Device: screen size (
devices), operating system (os) and browser (browsers) - Schedule:
- start and end times (
start,end) - days of the week (
days) and a daily time window (timeFrom,timeTo) - in the site's or the visitor's time zone (
scheduleTz) - a popup whose end has passed loads nowhere
- start and end times (
- Signed-in people (
hide): hide it from everyone signed in, or from chosen roles - Split testing (
split): popups that share a group name show one of them to each browser. The first page with any of them picks one at random from those it has, and that browser keeps it from then on. A page without the picked one shows none of the group
Most rules are decided in the visitor's browser, so pages stay cacheable. Counts are kept in that browser's localStorage and sessionStorage under the key kindly-popups. Signed-in rules are decided on the server, so a page that gets a popup with signed-in rules is sent as uncacheable.
Responsive sizes#
layout.width, height, h, v and edge can each be set per screen size. In the editor, switch the screen size (Tablets or Phones) and change them. In the JSON they are layout.tablet and layout.phone. Anything left out falls back to the larger screen's value: phone to tablet, then to desktop. To show a popup only on some screen sizes, use rules.devices.
Accessibility#
- With an overlay, the popup is a modal dialog:
role="dialog"andaria-modal, labeled by its first heading. Focus moves in and stays in, the rest of the page is inert, and page scrolling stops unlessbehavior.pageScrollis on. - Without an overlay, the page stays usable. Focus moves in only when the popup was opened by hand.
behavior.focuschooses whether focus goes to the first control or to the box.- On close, focus returns to where it was before the popup took it. Links and elements that open popups get
aria-expanded. - Animation respects reduced motion.
Don't override any of this.
Tracking#
- DOM events. Every opening, closing and conversion fires a DOM event on the popup that bubbles to the document:
kindly-popup:open,kindly-popup:closeandkindly-popup:convert, withdetail.id. A conversion is a form inside it being sent or a link inside it being followed. - dataLayer. When
behavior.dataLayeris on and the page has adataLayer, the same events are pushed askindly_popup_open,kindly_popup_closeandkindly_popup_convert, withpopup_idandpopup_name. - Built-in counts. When
behavior.statsis on, the visitor's browser sends only the counts of openings, conversions and closes. Nothing about the visitor is sent. Counts are stored per popup per day for 120 days, capped at 600 events a minute for each popup (filtercantata_edit_popup_events_per_minute). Anyone can send an event, so treat them as approximate. They appear in the Popups list and in the panel's Advanced section. Site managers don't count.
REST (/wp-json/cantata-edit/v1)#
| Route | Who | Does |
|---|---|---|
GET /popups |
editors | The published popups, with ID, name, status and anchor. Managers also get drafts and counts |
POST /popups {title, template?, kind?} |
managers | A new draft popup, empty, from a template, or from a kind |
DELETE /popups/{id} |
managers | Moves it to the trash |
POST /popups/{id}/duplicate |
managers | A draft copy |
POST /popups/{id}/status {on} |
managers | Turns it off (draft) or back on. Turning on requires that it was published from the editor before |
GET /popups/schema |
editors | Every setting, rule type, trigger type and kind, live from the code |
POST /popups/{id}/event {e} |
anyone | view, convert or close, counted as described above |
GET /popups/{id}/stats?days=30 |
managers | Daily counts, up to 120 days |
DELETE /popups/{id}/stats |
managers | Clears them |
Connected builders change a popup's content and settings the same way they change a page: write the box with its data-ke-popup JSON and save. An invalid setting fails the save and names the setting.
Examples#
A newsletter slide-in after half the page, once a week, not for people who already signed up:
{
"layout": { "width": "380px", "h": "right", "v": "bottom", "overlay": false, "in": "up", "out": "up", "phone": { "width": "100%", "h": "center" } },
"behavior": { "submitClose": 3, "afterSubmit": "never" },
"where": { "include": [ { "t": "type", "v": "post" } ] },
"when": [ { "t": "scroll", "dir": "down", "pct": 50 } ],
"rules": { "times": 1, "per": "week" }
}
An exit-intent offer for first-time visitors from search, during a sale:
{
"where": { "include": [ { "t": "all" } ], "exclude": [ { "t": "url", "v": "/checkout/" } ] },
"when": [ { "t": "exit", "top": 10, "mobile": true } ],
"rules": { "visitor": "new", "from": "search", "start": "2026-11-27T00:00", "end": "2026-12-01T23:59" }
}
A "Book a visit" button that opens a booking popup, with no rule loading it anywhere. The page brings it along:
<a class="button" href="#kindly-popup-42">Book a visit</a>
<span data-ke-popup-open="42" data-ke-popup-on="hover">Hours</span>
Not included, on purpose#
These are left out deliberately. Don't add them as custom code. If one is needed, it becomes a setting in the table first.
| Feature | Why it's left out |
|---|---|
| Sound on open | Unwelcome and blocked by browsers |
| Location targeting | Needs a third-party lookup and personal data |
| Cart and shop rules | Belong to the shop plugin's own blocks |
| Back-button exit intent | Hijacks navigation |
| Inline and teaser popup types | Use ordinary page content, and a slide-in kind for a teaser |
| Spin-to-win and gamified popups | Not offered |
| Overlay images and gradients | The overlay is a color and an optional blur |
| Weighted or server-side split tests | Splits are even and per browser |
Multi-step flows use a Kindly form's steps or popups chained with links.