Complete popup settings
Every popup setting, allowed value, default, page rule, trigger, and starting kind.
Generated from includes/popups.php by bin/popup-docs.php. Do not edit by hand: change the table in cantata_edit_popup_schema() and run wp eval-file bin/popup-docs.php. Read POPUPS.md first for how popups work. The same table is popup-settings.schema.json and GET /wp-json/cantata-edit/v1/popups/schema.
A popup's settings are one JSON object with five parts: layout, behavior, where, when and rules. Anything left out takes its default. A key that isn't listed here is refused by name, never dropped.
layout: size, place, overlay, close button, animation#
| Key | Values | Default | What it does |
|---|---|---|---|
width |
a length in px, vw, %, rem, em | "640px" |
The box's width, never wider than the screen. |
height |
auto, screen or a length in px, vh, rem, em, % |
"auto" |
auto fits what is inside; screen fills the screen's height (less the edge); a length scrolls longer content inside. |
h |
left, center, right |
"center" |
Where it sits across the screen. |
v |
top, center, bottom |
"center" |
Where it sits up and down the screen. |
edge |
a length in px, rem, em, vw, vh, % (or 0) | "16px" |
The space kept between the box and the screen's edges. 0 for bars and full-screen popups. |
tablet |
an object of width, height, h, v, edge | {} |
Tablet overrides of width, height, h, v and edge. Anything left out is the desktop value. |
phone |
an object of width, height, h, v, edge | {} |
Phone overrides of width, height, h, v and edge. Anything left out is the tablet value, then the desktop one. |
overlay |
true or false | true |
Dim the page behind it. On: a modal (focus stays inside, the rest of the page is inert). Off: the page stays usable. |
overlayColor |
a color | "rgba(16,24,40,0.6)" |
The overlay's color; its alpha is how much it covers. |
overlayBlur |
0 to 20 | 0 |
Blur the page behind the overlay, in pixels. |
close |
inside, outside, none |
"inside" |
The close button: inside the box's corner, outside it, or none. |
closeAt |
right, left |
"right" |
Which top corner the close button sits in. |
closeDelay |
0 to 60 | 0 |
Seconds before the close button appears. Esc and the overlay still close it unless turned off. |
closeSize |
12 to 64 | 28 |
The close mark's size in pixels. Its target stays at least 44 pixels square. |
closeColor |
a color or "" (the theme's) | "" |
The close mark's color. Empty: the box's text color (white outside the box). |
closeBg |
a color or "" (the theme's) | "" |
The close button's background. Empty: none. |
closeHoverColor |
a color or "" (the theme's) | "" |
The close mark's color on hover and keyboard focus. Empty: unchanged. |
closeHoverBg |
a color or "" (the theme's) | "" |
The close button's background on hover and keyboard focus. Empty: unchanged. |
in |
none, fade, zoom, zoom-out, up, down, left, right, flip, rotate, bounce, blur |
"fade" |
The opening animation. up: rises into place; left: comes in from the right. |
out |
none, fade, zoom, zoom-out, up, down, left, right, flip, rotate, bounce, blur |
"fade" |
The closing animation, played in reverse: up leaves downwards. |
time |
0 to 3000 | 300 |
The opening animation's length in milliseconds. |
outTime |
0 to 3000 | 300 |
The closing animation's length in milliseconds. Left out: the same as time. |
ease |
ease, linear, ease-in, ease-out, ease-in-out, spring |
"ease" |
The animations' easing. spring overshoots a little and settles. |
z |
1 to 2147483000 | 99990 |
Its stacking order (z-index) over the page. |
behavior: closing, opening by hand, forms, snoozing, tracking#
| Key | Values | Default | What it does |
|---|---|---|---|
autoClose |
0 to 600 | 0 |
Close by itself after this many seconds. 0: stays until closed. |
overlayCloses |
true or false | true |
A click on the overlay closes it. |
escCloses |
true or false | true |
The Esc key closes it. |
pageScroll |
true or false | false |
The page can scroll behind a modal. |
single |
true or false | true |
Never opens by itself while another popup is open. |
selector |
a CSS selector or "" | "" |
Elements matching this CSS selector open it when clicked (or Enter and Space on them). Prefer the element setting Advanced > Popup, which needs no selector. |
closeOthers |
true or false | false |
Opening it closes any other open popup first. |
linkCloses |
true or false | false |
Following any link inside it closes it first (for menus and jump links). |
submitClose |
-1 to 60 | -1 |
After a form inside it is sent: -1 stays open (showing the form's message), 0 closes at once, a number closes after that many seconds. |
afterSubmit |
never, wait, none |
"never" |
After a form inside it is sent: never stops it opening by itself again for that visitor; wait stops it for afterSubmitDays; none changes nothing. |
afterSubmitDays |
1 to 365 | 30 |
With afterSubmit wait: how many days. |
snooze |
0 to 365 | 0 |
After a visitor closes it, it does not open by itself again for this long. 0: no wait. |
snoozeFrom |
close, open |
"close" |
When the snooze starts: when the visitor closes it, or as soon as it opens. |
snoozeUnit |
hours, days |
"days" |
The unit of snooze. |
focus |
first, box |
"first" |
Where keyboard focus goes when it opens: the first control inside, or the box itself (screen readers start at the top). |
dataLayer |
true or false | true |
Also tell the site's own Google Tag Manager or Analytics (window.dataLayer, when the site has one): kindly_popup_open, kindly_popup_close and kindly_popup_convert, with popup_id and popup_name. |
stats |
true or false | true |
Count views, conversions and closes for the Popups list. Counts only, per day: nothing about the visitor is kept. |
rules: who sees it, how often, schedule#
| Key | Values | Default | What it does |
|---|---|---|---|
views |
0 to 1000 | 0 |
Opens by itself only after the visitor has viewed this many pages on the site. |
sessions |
0 to 1000 | 0 |
Opens by itself only after this many visits (a visit is a browser tab's session). |
visitor |
any, new, returning |
"any" |
new: on the visitor's first visit only; returning: from their second visit on. |
times |
0 to 1000 | 0 |
Opens by itself at most this many times (per). 0: no limit. Opening by hand does not count. |
per |
ever, session, day, week, month |
"ever" |
What times counts within: ever in this browser, each visit, each day, each week (from Sunday) or each month. |
from |
any, search, social, ai, external, internal, url |
"any" |
Where the visitor arrived from (the page's referrer): a search engine, a social network, an AI assistant, another site, this site, or an address containing fromUrl. |
fromUrl |
text, up to 200 characters | "" |
With from url: words the referring address contains. |
fromNot |
true or false | false |
Turns the from rule around: opens for everyone except visitors arriving that way. |
query |
a list of up to 5 | [] |
Address parameters that must all be present, as name or name=value (such as utm_source=newsletter). |
popups |
a list of up to 5 | [] |
Other popups this visitor must (or must not) have seen, closed or converted with, as ID:seen, ID:closed, ID:converted, ID:not-seen or ID:not-converted. All must hold. |
cookie |
text, up to 64 characters | "" |
A cookie's name to check. Empty: no cookie rule. |
cookieHas |
true or false | true |
true: opens only when the cookie is set; false: only when it is not. |
devices |
any of desktop, tablet, phone (at least 1) |
["desktop","tablet","phone"] |
Screen sizes it opens by itself on, from the site's own screen sizes. |
os |
any of windows, mac, ios, android, linux, chromeos |
[] |
Only on these operating systems. Empty: every one. |
browsers |
any of chrome, edge, firefox, safari, opera, samsung |
[] |
Only these browsers. Empty: every browser. |
start |
YYYY-MM-DDTHH:MM (site time) or "" |
"" |
Opens by itself from this date and time (the site's time zone). Empty: no start. |
end |
YYYY-MM-DDTHH:MM (site time) or "" |
"" |
Until this date and time (the site's time zone). Empty: no end. After it, pages no longer load it. |
scheduleTz |
site, visitor |
"site" |
Whose clock start, end, days and times of day are read on: the site's time zone or the visitor's own. |
days |
weekday numbers, 0 Sunday to 6 Saturday | [] |
Only on these weekdays (0 Sunday to 6 Saturday, the site's time zone). Empty: every day. |
timeFrom |
HH:MM or "" |
"" |
Only from this time of day (HH:MM, the site's time zone). With timeTo earlier, the window runs past midnight. |
timeTo |
HH:MM or "" |
"" |
Only until this time of day (HH:MM, the site's time zone). |
hide |
none, in, roles |
"none" |
Signed-in people: show to everyone, hide from everyone signed in, or hide from some roles. Decided on the server: pages that get such a popup are sent uncacheable. |
roles |
role names on the site | [] |
With hide roles: the roles it is hidden from. |
split |
text, up to 40 characters | "" |
A split-test group name. Of the popups loaded on a page that share it, each visitor is given one at random (kept in their browser) and only that one opens by itself. Compare them in the Popups list. |
where: rule types#
where.include and where.exclude are lists of up to 30 rules each. Exclude wins.
t |
Matches |
|---|---|
all |
Every page. |
front |
The front page. |
blog |
The posts page. |
type |
Every single page of a kind: { "t": "type", "v": "post" }. |
ids |
These posts or pages: { "t": "ids", "v": [12, 34] }. |
child |
Pages directly under these: { "t": "child", "v": [12] }. |
descendant |
Pages anywhere under these: { "t": "descendant", "v": [12] }. |
term |
In these categories or tags, and their archives: { "t": "term", "tax": "category", "v": [3], "deep": true } (deep: child terms too). |
author |
By these authors, and their archives: { "t": "author", "v": [1] }. |
ptarchive |
A kind's own archive: { "t": "ptarchive", "v": "product" }. |
archive |
Every archive, the posts page and search results. |
date |
Date archives. |
search |
Search results. |
404 |
Page not found. |
template |
Pages using this page template file: { "t": "template", "v": "templates/landing.php" }. |
url |
Addresses whose path contains these words: { "t": "url", "v": "/shop/" }. |
when: trigger types#
Up to 10 triggers, each type once. Any one opens the popup.
t |
Opens it |
|---|---|
load |
After the page has loaded: { "t": "load", "delay": 3 } (seconds, 0 to 600). |
scroll |
Scrolling: { "t": "scroll", "dir": "down", "pct": 50 } (down past pct of the page, or up after having scrolled down). |
scrollTo |
An element coming into view: { "t": "scrollTo", "sel": "#sign-up" }. |
clicks |
After a number of clicks on the page: { "t": "clicks", "n": 3 } (1 to 50). |
idle |
After a time without activity: { "t": "idle", "s": 30 } (seconds, 1 to 3600). |
exit |
Exit intent: the pointer leaving the top of the page on computers ({ "t": "exit", "top": 0 }: how many pixels from the top edge count, 0 to 150); "mobile": true also a quick scroll back up on phones and tablets. |
hover |
The pointer resting on an element: { "t": "hover", "sel": ".pricing" }. |
time |
Time on the site this visit: { "t": "time", "s": 60 } (seconds, 1 to 7200). |
adblock |
The visitor's browser blocks ads: { "t": "adblock" }. |
return |
The visitor comes back to this tab after leaving it for a while: { "t": "return", "s": 10 } (seconds away, 1 to 3600). |
Kinds#
The starting layout a new popup gets (POST /popups with kind). After that it's ordinary settings.
| Kind | Name | Layout it starts with |
|---|---|---|
modal |
Modal | the defaults |
slide-in |
Slide-in | {"width":"380px","h":"right","v":"bottom","overlay":false,"in":"up","out":"up","phone":{"width":"100%","h":"center"}} |
bar-top |
Bar at the top | {"width":"100%","v":"top","edge":"0","overlay":false,"in":"down","out":"down"} |
bar-bottom |
Bar at the bottom | {"width":"100%","v":"bottom","edge":"0","overlay":false,"in":"up","out":"up"} |
full |
Full screen | {"width":"100%","height":"screen","edge":"0","in":"fade","out":"fade"} |
side-left |
Side panel, left | {"width":"400px","height":"screen","h":"left","edge":"0","in":"right","out":"right","phone":{"width":"88vw"}} |
side-right |
Side panel, right | {"width":"400px","height":"screen","h":"right","edge":"0","in":"left","out":"left","phone":{"width":"88vw"}} |