web_listings Shortcode

The web_listings shortcode renders the listings (Feed) 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.

Usage

[web_listings]

Attributes

Attribute Default Accepted values Purpose
query_type default custom, default, single_post, current Latest 12 posts, a saved query, ordered selected IDs, or the current archive/search request.
posts_per_page Source limit Positive integer or -1 for all results Overrides the ordinary source limit; Faceted Search owns its own page size.
accessible_name Empty Plain text Names the results region for assistive technology.
single_post — A value selected from WordPress Controls the single posts. Available when query_type is single_post.
custom_query 1 String unless stated otherwise Controls the custom queries. Available when query_type is custom.
related_split_<post-type-slug>_title Related <post-type label> Plain text Customizes the heading for each publicly queryable post type when related_display_mode is split. The Page Builder creates one control per available post type on the current site.
faceted_search no yes, no Controls the use with faceted search?.
submit_mode auto auto, manual Controls the facet submit mode. Available when faceted_search is yes.
show_initial_results yes yes, no Controls the show initial results?. Available when faceted_search is yes.
submit_on_reset yes yes, no Controls the refresh after reset?. Available when submit_mode is manual.
initial_results_placeholder — String unless stated otherwise Controls the initial results placeholder. Available when show_initial_results is no.
only_related — yes Controls the only related to current post. Available when faceted_search is no.
exclude_current_post_from_query yes yes If the feed is displayed in any Single and the current post appears in the query, it will be skipped. Available when faceted_search is no.
exclude_hidden_products yes yes Controls the exclude hidden woocommerce products. Available when faceted_search is no.
related_display_mode mix mix, split Controls the related posts display mode. Available when only_related is yes.
enable_pagination — yes Controls the enable pagination. Available when faceted_search is no.
prevent_pagination — yes Prevent the main query from paging this feed. Available when faceted_search is no.
pagination paginated paginated, paginated_no_ajax, load_more, infinite Controls the pagination style. Available when enable_pagination is yes.
load_more_text Load more String unless stated otherwise Controls the "load more" button text. Available when pagination is load_more.
load_more_style 1 1 or a configured button-style slug Selects the Load More button style. Available when pagination is load_more.
style default default, default_masonry, only_image, horizontal_list, horizontal_list_thumbnail, horizontal_list_big, horizontal_list_title_over, horizontal_list_creative, wide_slider, full_screen, full_width_section, pricing_list, no_wrapper Controls the feed wrapper style.
layout default default or a configured custom feed-template slug Selects the template used for each feed result.
columns_default 4 12, 6, 4, 3, 2 Controls the number of columns. Available when style is default.
columns_default_tablet_h 12 12, 6, 4, 3, 2 Controls the number of columns on tablet (horizontal). Available when style is default.
columns_default_tablet_v 12 12, 6, 4, 3, 2 Controls the number of columns on tablet (vertical). Available when style is default.
columns_default_mobile 12 12, 6, 4, 3, 2 Controls the number of columns on mobile. Available when style is default.
columns 2 1, 2, 3, 4, 5, 6, 7, 8, 9 Sets the number of result columns. Available when style is default_masonry or only_image.
gap Empty (theme default) default, minimal, small, medium, none Controls grid or masonry spacing, including the image-hover grid.
wide_slider_adapt — yes Controls the enable adaptive height. Available when style is wide_slider.
feed_wide_slider_ajax Empty Retained stored attribute No independent effect. Use enable_pagination and pagination for loading additional wide-slider results.
loading_background_color — String unless stated otherwise Choose loading background color.
loading_background_alpha 50 Number Controls the loading background alpha.
loading_background_image — String unless stated otherwise Controls the loading background image.
device_visibility — String unless stated otherwise Applies the selected responsive visibility rule.
el_id — Valid unique HTML ID Enter section 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.

Choose a query and template

Use a saved custom query when the listing has reusable selection rules. Use the current archive context for an archive result area. Select a deliberate custom feed template for each card and verify that it contains the fields the visitor needs.

When faceted_search="yes", add facets and controls for the same context. Choose automatic or manual submission and decide whether the unfiltered list should be visible.

Only published, password-free public content allowed by current content-type permissions is rendered. Empty explicit selections, deleted queries and empty related intersections produce no unrelated fallback. Current-context mode requires a real archive/search request. Authored page sizes, all-results queries and ordered ID selections are preserved, including during AJAX pagination. Related split mode groups all matching related results without independent pagers; use mixed mode to paginate. Recursive card expansion remains bounded without truncating an ordinary top-level collection.

Grid gap values minimal, small, medium and none apply existing per-side padding helpers of 0.375rem, 0.75rem, 1.25rem and zero. Masonry retains its existing Isotope gap scale. All four column widths, spacing and visibility remain consistent on subsequent AJAX pages. Explicit IDs identify the listing, not its classes.

The equivalent Listings block uses the same renderer and assets. Legacy administration can be disabled without disabling public shortcode rendering. Pagination supports static HTML page caching without an expiring visitor nonce. Previously cached pagers recover from a public referring page when their current saved configuration is identifiable, including multiple listings, explicitly included published content, synced patterns and native text/block widgets. Equivalent duplicates are accepted. Old archive/split-context pagers, dynamically supplied templates, indistinguishable listings or missing same-site referrers require fresh page HTML. Browser-provided queries and template paths are never executed. No stored-shortcode migration is needed.

Saved query behavior

An existing custom query with an empty, zero or omitted page size uses 100 results unless the shortcode supplies an override. Latest-posts sources retain their 12-result default; related split output has its own all-results behavior. Historical taxonomy selector rows use any selected term within a taxonomy and require every selected taxonomy group. Explicitly structured taxonomy queries retain their own nested AND/OR conditions.

Canonical URLs for numbered pages

A page containing a native web_listings shortcode with enable_pagination="yes" uses its numbered URL as the canonical on page 2 and later. For example, /projects/page/2/ stays distinct from /projects/. This applies to WordPress, Rank Math and Yoast canonical output. An explicit canonical pointing to another resource is preserved.

The listing must participate in normal page pagination: prevent_pagination="yes" and faceted_search="yes" are excluded. Equivalent native Listings blocks in the saved page, including nested blocks, also retain numbered canonicals. Listings included indirectly through synced patterns or external templates are outside this detection. Related split blocks do not expose independent numbered pages.

After saving, open the first page and a numbered page. Check that the results change and inspect each page's canonical link in the HTML source. Query-string and pretty-permalink formats follow the site's WordPress permalink configuration.

Standard pagination without AJAX gives its arrow links translated “Previous page” and “Next page” names. Check both arrows on an intermediate page with a keyboard or screen reader; their icons remain decorative and the destinations follow the same WordPress pagination URLs.

Verification

Test web_listings with populated, empty and long result sets, and verify the selected source belongs to the current site. Pay particular attention to query_type and single_post.

`web_line` Shortcode
Previous
`web_image_comparer` Shortcode
Next