Kindly EditDocumentationTry the editor

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"}}
About this page

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

Type a word or phrase to search the full documentation.