Kindly EditDocumentationTry the editor

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.md or docs/popup-settings.schema.json by hand. Change cantata_edit_popup_schema() and run wp eval-file bin/popup-docs.php. tests/popups-full-test.php fails 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's data-ke-popup attribute 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:

  1. Where it loads (where.include). The popup loads on matching pages and can open by itself through its when triggers. 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
  2. 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 where rule 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-close or #kindly-popup-close-never, and any link inside if behavior.linkCloses is on.
  • After a form inside is sent (behavior.submitClose).
  • Opening another popup closes it if behavior.closeOthers is 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)
  • Frequency:
    • at most times openings per visit, day, week, month or ever
    • snoozed for some hours or days after closing or opening (behavior.snooze, snoozeFrom, snoozeUnit)
  • Where they came from (from):
    • search engines, social sites, AI assistants, other sites, this site, or a referrer containing given words (fromUrl)
    • fromNot inverts it
  • The address and browser:
    • address parameters (query, such as utm_source=news or just promo)
    • a cookie being present or absent (cookie, cookieHas)
  • 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
  • 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" and aria-modal, labeled by its first heading. Focus moves in and stays in, the rest of the page is inert, and page scrolling stops unless behavior.pageScroll is on.
  • Without an overlay, the page stays usable. Focus moves in only when the popup was opened by hand.
  • behavior.focus chooses 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:close and kindly-popup:convert, with detail.id. A conversion is a form inside it being sent or a link inside it being followed.
  • dataLayer. When behavior.dataLayer is on and the page has a dataLayer, the same events are pushed as kindly_popup_open, kindly_popup_close and kindly_popup_convert, with popup_id and popup_name.
  • Built-in counts. When behavior.stats is 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 (filter cantata_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.

About this page

Documents Kindly Edit 0.9.16. Source: docs/POPUPS.md. Theme choices and account permissions can change which controls appear.

Type a word or phrase to search the full documentation.