Popups

Quick start

1. Go to XPAC → Popups → All Popups.
2. Click Add New Popup.
3. Build the popup with normal WordPress blocks.
4. Open Display Rules in the editor sidebar.
5. Add a rule and publish the popup.

A popup with no rule will not open by itself. You can still open it with a Popup Selector block.

Popup types

Display rules

Every rule answers three questions:

1. Where? Choose the pages, posts, URLs or query strings.
2. When? Choose a trigger.
3. How? Choose the popup type, position, animation and close button.

You can add more than one rule to a popup. A rule must be enabled and inside its start/end dates.

Inline popups need a page condition but do not need a trigger.

Triggers

Closing

• Escape always closes a lightbox or floating bar.
• The close button is optional.
• Clicking outside can close a lightbox.
• A button or link with class xpac-popup-cta-close closes its popup.
• Escape removes an inline popup only while focus is inside that popup.

Popup Selector block

Use the Popup Selector block when a visitor should choose to open a popup.

1. Add the block to a post or template.
2. Select a published popup.
3. Put a button, image or other blocks inside it.

The inner content becomes the opener.

Site settings

Go to XPAC → Popups → Settings.

Path examples:

/checkout
/account/*

/checkout matches one path. /account/* also matches paths below /account.

Statistics

The Overview shows four counts:

• Could have opened — the popup was available on the page.
• Opened — the popup appeared.
• Closed — the visitor dismissed it.
• Clicked — the visitor clicked a control inside it.

Each count is recorded at most once per popup per page view. Editors are not counted. No visitor identity is stored.

Styling

Popups use the active theme's theme.json values for the surface, text, content size, spacing and shadow. Blocks inside the popup keep their normal WordPress styles.

The plugin only supplies the popup frame, placement, overlay and close button. It does not force a brand palette or font.

Add a class under Popup Settings → Advanced → Additional CSS class(es) when one popup needs a custom look:

.sale-popup {
  --xpac-pp-width: 38rem;
  --xpac-pp-container-padd: 3rem;
  --xpac-pp-shadow: var(--wp--preset--shadow--deep);
}

Useful variables:

Use WordPress preset variables where possible. This keeps the popup correct when the site switches styles or color schemes.

Accessibility

• Lightboxes use a modal dialog, move focus inside and trap Tab until closed.
• Closing returns focus to the element that opened the popup.
• Floating and inline popups use a named region and do not trap focus.
• Background content becomes inert only while a lightbox is open.
• Reduced-motion preferences replace movement with a short fade.

Import and export

Use Export as JSON from the popup list. Use Import to preview a file before creating anything.

Imported popups are not published automatically.

Troubleshooting

The popup never opens

Check these in order:

1. The popup is published.
2. The rule is enabled.
3. The rule has a page condition.
4. A lightbox or floating bar has a trigger.
5. The schedule includes today.
6. Popups are not paused.
7. The current path is not excluded.

The popup looks different from the editor

Put background, text and spacing styles on a Group or Cover block inside the popup. Check whether theme CSS targets only .wp-site-blocks; popup markup is added directly to the document body.

Inline content is missing

Try After Footer first. Before Header needs the theme to call wp_body_open().

Developers

See the Popups hook reference for every public action and filter.