web_modal Shortcode
The web_modal shortcode renders the modal component.
The attributes below match the current Page Builder controls and public output. Use raw syntax only for reviewed content that cannot be maintained through the visual controls.
Allowed child shortcodes: web_modal_content.
Usage
[web_modal]
Content
[/web_modal]Attributes
| Attribute | Default | Accepted values | Purpose |
|---|---|---|---|
modal_title |
— | String unless stated otherwise | Title displayed on the top of the modal. |
modal_aria_label |
— | String unless stated otherwise | Add an ARIA label for accessibility . |
modal_button_text |
— | String unless stated otherwise | Add text to button. |
modal_width |
large |
small, large, extra_large |
Choose the width of the modal. |
modal_background_url |
— | String unless stated otherwise | Controls the modal background. |
modal_background |
— | String unless stated otherwise | Select background image. |
popup_hide_button |
— | yes |
If selected there will be no button to open modal. |
button_style |
1 |
1 or a configured button-style slug |
Chooses a button style defined in the POM design system. |
popup_on_page_load |
— | yes |
If selected modal will open when page is loaded. |
popup_on_page_load_time |
— | Integer milliseconds, 0–86400000 | Delay before automatic opening. Available when popup_on_page_load is yes. |
popup_open_only_once |
— | yes |
Remember any successful dismissal for this Modal ID in this browser and suppress its automatic reopening. Other modals and manual triggers remain available. Browser storage restrictions or clearing site data can reset the remembered state. |
popup_open_if_tab_change |
— | yes |
The pop-up opens after the visitor leaves this browser tab and returns to it. |
dont_close_when_clicking_outside |
— | yes |
Disable both outside-click and Escape closing. The close button remains available. |
schedule_start_date |
— | YYYY-MM-DD |
Inclusive first local-calendar date for automatic opening; may be used without an end date. |
schedule_end_date |
— | YYYY-MM-DD |
Inclusive last local-calendar date for automatic opening; may be used without a start date. |
device_visibility |
— | String unless stated otherwise | Applies the selected responsive visibility rule. |
el_id |
— | Valid unique HTML ID | Enter element ID (Note: make sure it is unique and valid according to w3c specification). |
el_class |
— | String unless stated otherwise | If you wish to style particular content element differently, then use this field to add a class name and then refer to it in your css file. |
Enclosed content
Content between the opening and closing tags is processed as WordPress shortcode content. Keep the parent/child structure shown by the visual builder so nested components receive the context they expect.
Every direct web_modal_content section is retained in order. A missing ID receives an automatic ID, but use a stable explicit el_id for external triggers and remembered dismissal. Dates use the visitor's local calendar and affect automatic opening only; they are not access-control rules. Invalid or reversed dates suppress automatic opening. Manual triggers still work.
Loading behavior
Rendering the shortcode conditionally enqueues the shared Modal stylesheet, Bootstrap behavior, and shortcode controller in the initial document. Pages without a modal do not request those files. Automatic, delayed, scheduled, tab-return, and open-only-once choices therefore remain ready without waiting for a visitor interaction.
The behavior is compatible with signed-out cached pages and signed-in dynamic pages. Developers adding custom modal integrations should follow the conditional asset delivery guide and use the registered Modal feature or handles.
The shared controller keeps one dialog open at a time, traps keyboard focus and returns it to the page trigger. It does not let automatic opening interrupt another open dialog. The Gutenberg Modal family uses the same behavior and assets.
Verification
Populate web_modal with web_modal_content and confirm every child remains reachable in the intended order. Open, close, and reopen the modal; test keyboard focus and Escape; and verify any automatic delay or open-only-once choice in a signed-out session. Pay particular attention to modal_title and modal_aria_label.