Post Widget
Post Widget Settings
Posts Per Page
Define the number of posts displayed per page.
Details: Set the number of posts to show, from -1 to 100. Default: 3. Use -1 to display all posts. When pagination is on, this is the number of posts on each page.
Layout
Choose the layout for displaying posts.
Details: Select a layout to control the presentation of posts on the page.
Options:
| Layout | Description |
|---|---|
| Grid | Arranges posts in a uniform grid. This is the default. |
| Masonry | Creates a staggered layout where each post keeps its natural height. |
| Carousel | Displays posts in a sliding carousel. See Carousel Settings. |
| Feed Layout | Groups posts under a heading for each of their terms. See Feed Layout below. |
Feed Layout
Group posts into sections by term.
Details: Each post is placed under a heading for every term it belongs to (categories, tags and other public taxonomies). A post with several terms appears in each of its sections. If you set Include or Exclude terms in the Query section, only the matching terms create sections. Pagination controls are not shown in this layout.
Options:
| Setting | Description |
|---|---|
| Show Posts Without Terms | Adds a section for posts that have no term. |
| Uncategorized Title | Set the heading of the section for posts without terms. Default: “Uncategorized”. Available when Show Posts Without Terms is on. |
| Filter Buttons | Copy the feed_filters id="…" shortcode and place it anywhere on the page. It shows an “All” button plus one button per term. Clicking a button shows only that term’s section. |
| Anchor Buttons | Copy the feed_anchor_filters id="…" shortcode and place it anywhere on the page. It shows one link per term that jumps to that term’s section. |
Post Skin
Select the visual style for posts.
Details: Choose a skin to customize the appearance of each post.
Options:
| Skin | Description |
|---|---|
| Classic | Standard layout with the image above the content. This is the default. |
| On Side | Places image and content side by side. |
| Banner | Places the content over a large image. |
| Template Grid | Builds each post from an Elementor template you choose. |
| Custom HTML | Lets you write the HTML of each post yourself. |
Keep Sideways on Mobile
Maintain the “On Side” layout on mobile devices.
Details: When enabled, the “On Side” skin keeps its side-by-side layout on mobile. Available only when “On Side” is selected as the post skin.
Columns
Set the number of columns for the grid layout.
Details: Choose 1 to 8 columns. The setting is responsive, so you can use a different number per device. Default: 3 on desktop and tablet, 1 on mobile.
Options:
| Option | Description |
|---|---|
| 1–8 Columns | Define the column count for desktop, tablet, and mobile. |
Post HTML Tag
Choose the HTML tag for each post.
Details: Select the semantic tag for post containers. Default: article.
Options:
| Tag | Description |
|---|---|
| div | Generic container for flexible styling. |
| article | Semantic tag for independent content. |
Tips:
- Use article for blog posts or products that make sense on their own.
- Choose div for non-semantic layouts.
Title HTML Tag
Choose the HTML tag for post titles.
Details: Select the tag for post titles to control semantics and styling. Default: h3. Not available for the Template Grid skin.
Options:
| Tag | Description |
|---|---|
| h1 | Main heading. Use only if the page has no other h1. |
| h2 | Section heading. |
| h3 | Sub-section heading. This is the default. |
| h4 | Lower-level heading for nested content. |
| h5 | Minor heading. |
| h6 | Smallest heading. |
| div | Non-semantic container. |
| span | Inline container. |
| p | Paragraph tag for text-style titles. |
Default Template
Select the template used for each post.
Details: Choose an Elementor template to render every post. Available only when “Template Grid” is selected.
Extra Templates
Insert additional templates into the grid.
Details: Turn on Add Extra Templates (requires a Default Template), then add one entry per extra template. Use them for ads, banners or call-outs between posts.
Options:
| Setting | Description |
|---|---|
| Choose a Template | Choose the Elementor template to insert. |
| Position | Set the template’s position in the grid (1 or higher). Default: 1. |
| Apply Once | On, the template appears once at its position. Off, it repeats at that interval. Default: on. |
| Column Span | Set how many columns the template spans (1–8). Responsive. |
| Row Span | Set how many rows the template spans (1–8). Responsive. |
Custom HTML
Define custom HTML for each post.
Details: Available only when “Custom HTML” is selected as the post skin. Write your markup with these tags, which are replaced for each post:
Available Tags:
| Tag | Replaced with |
|---|---|
#TITLE# | The post title. |
#CONTENT# | The post content. |
#EXCERPT# | The post excerpt. |
#PERMALINK# | The post URL. |
#IMAGE# | The featured image, as a responsive <img> using your Image Size setting. Developers can change the markup with the bpfwe_custom_html_image filter. |
#ID# | The post ID. |
Post Content
Choose what each post shows. Available for every skin except Template Grid.
Featured Image
Control the image shown with each item.
Details: Featured images are output as real responsive images, with srcset, width and height attributes and native lazy loading. The image’s own alt text is used, or none if the image is decorative.
Options:
| Setting | Description |
|---|---|
| Show Featured Image | Show or hide the image. Default: on. |
| Image Size | Choose the WordPress image size to load, or set a custom size. Default: Thumbnail. |
| Term Image Key | For Taxonomy Query only. The term meta key that stores the image. Default: bpfwe_swatches_image, the key used by swatch images. |
| User Image Key | For User Query only. The user meta key that stores the image. |
| Link to Post | Make the image a link to the post. |
Style tab: The Featured Image style section controls the display of the image.
- Image Equal Height (default: on) gives every image the same shape. Choose an Aspect Ratio: 3:2 (default), 1:1, 4:3, 16:9 or 1.91:1. The ratio is applied with CSS, so the layout doesn’t jump while images load.
- Turn Image Equal Height off to set a fixed Height instead.
- Fallback Image is shown for posts that have no featured image.
Content
Configure the content displayed in each post.
Details: Add one entry per item in the order you want. Each entry has its own settings and a Custom style option for that row. The available items depend on the query type.
Options (Post Query and Main Query):
| Content Type | Description |
|---|---|
| Title | Displays the post title. Options: Link to Post, Title Length (number of words, default 6). |
| Content | Shows the post content, trimmed to a number of words (Content Length, default 12). |
| Excerpt | Shows the post excerpt, trimmed to a number of words (Content Length, default 12). |
| Custom Field/ACF | Shows the value of a custom field. Enter the Field Key, for example _price. |
| Taxonomy | Shows the post’s terms as links. Choose the taxonomy and the maximum number of terms (default 5). |
| HTML/Shortcode | Adds your own HTML or a shortcode. |
| Post Meta | Shows the author, date and comment count. Each can be turned on or off. Set the separator (default ” | “), the date format (default Y/m/d), the author link and an icon for each. |
| Read More | Adds a link to the full post. Default text: “Read More »”. |
| Bookmark | Lets visitors pin posts. See Bookmark Options. |
| Edit Options | Adds republish, unpublish, edit and delete actions. See Edit Options. |
| Product Price | Displays the product price (WooCommerce). |
| Product Rating | Shows the product rating (WooCommerce). |
| Buy Now | Adds a buy button (WooCommerce). Default text: “Buy Now”. |
| Add to Cart | Adds an add-to-cart button (WooCommerce). Default text: “Add to cart”. |
| Product Badge | Displays “On Sale”, “New Arrival” and “Best Seller” badges (WooCommerce). Each badge can be turned on or off and its text changed. |
Options (User Query): Username, Display Name, First/Last Name, Custom Field/ACF (user meta), User Email, User Role, User ID, Visit Profile (a link to the profile, default text “Visit Profile »”), and HTML/Shortcode. Names can link to the user’s profile.
Options (Taxonomy Query): Term Label, Term Description, Term Count (with singular and plural text, default “Post” and “Posts”), Custom Field/ACF (term meta), Term ID, Term URL, and HTML/Shortcode.
Custom Style: Turn on Custom in an entry to style that row on its own (size, weight, colors, background, border radius, position, padding, margin and z-index). Rows can also have Before and After text (use # in After to display the row number) and an icon.
Bookmark Options
Let visitors pin posts for quick access.
Details: Add the Bookmark content type to show a pin button on each post. Pinned post IDs are stored in a cookie named post_id_list for logged-out visitors and as user meta with the same key for logged-in users. To show only a visitor’s pinned posts, turn on Pinned Posts in the Query section.
Options:
| Setting | Purpose | Details |
|---|---|---|
| Bookmark | Add the pin button to each post. | Choose “Bookmark” as the content type of an entry. The settings below appear for that entry. |
| Icon | Select the icon shown on the button. | There are two icons: one for the pin state and one for the unpin state. |
| Bookmarked Text | Set the text of the pin button. | Default: “Pin”. |
| Unbookmarked Text | Set the text of the unpin button. | Default: “Unpin”. |
| Hide for Logged-Out Users | Hide the bookmark button for logged-out visitors. | When on, only logged-in users can pin posts. |
Edit Options
Give visitors actions to manage a post from the list.
Details: Add the Edit Options content type. Each action can be turned on or off and has its own icon and text.
Options:
| Setting | Purpose | Details |
|---|---|---|
| Display Republish | Enable the republish action. | On by default. |
| Republish Icon | Select an icon for the republish action. | Available when Display Republish is on. |
| Republish Text | Set the text of the republish action. | Default: “Republish”. |
| Display Unpublish | Enable the unpublish action. | On by default. |
| Unpublish Icon | Select an icon for the unpublish action. | Available when Display Unpublish is on. |
| Unpublish Text | Set the text of the unpublish action. | Default: “Unpublish”. |
| Display Edit | Enable the edit action. | On by default. |
| Edit URL | Set the page where posts are edited. | Use #ID# for the post ID, for example /your-edit-page?#ID#. Available when Display Edit is on. |
| Edit Icon | Select an icon for the edit action. | Available when Display Edit is on. |
| Edit Text | Set the text of the edit action. | Default: “Edit”. |
| Display Delete | Enable the delete action. | On by default. |
| Delete Icon | Select an icon for the delete action. | Available when Display Delete is on. |
| Delete Text | Set the text of the delete action. | Default: “Delete”. |
Query
Customize the query used to retrieve items.
Details: Configure what is displayed, in what order, and with which conditions.
Query Type
Select the type of query.
Details: Choose what the widget lists.
Options:
| Query Type | Description |
|---|---|
| Post Query | Fetch posts, pages or custom post types using the conditions below. This is the default. |
| Main Query | Use the main WordPress query of the current page, such as an archive or search results page. |
| User Query | List users instead of posts. Choose the roles and user meta to include. |
| Taxonomy Query | List the terms of a taxonomy instead of posts. |
Tips:
- Use Post Query for lists of your own choice.
- Choose Main Query for archive or search pages.
Post Type
Choose the type(s) of posts to retrieve.
Details: Select one or several post types, such as post, page, or custom types like product (if using WooCommerce). Available for Post Query. Default: post.
Taxonomy Query Options
Choose which terms are listed.
Details: Available for Taxonomy Query.
Options:
| Setting | Description |
|---|---|
| Select a Taxonomy | Choose the taxonomy whose terms are listed. |
| Display Empty Terms? | Show terms that have no posts. Default: yes. |
| Tax. Display Level | Choose Show All, Show Parent Only or Show Subcategory Only. |
| Filter Type | Include or exclude specific terms of the taxonomy. |
User Query Options
Choose which users are listed.
Details: Available for User Query.
Options:
| Setting | Description |
|---|---|
| Include by User Meta | Choose a user meta key to filter by. |
| Meta Value | The value the user meta must match. Available when a user meta key is chosen. |
| Include by Role | List only users with the selected roles. |
| Exclude by Role | Leave out users with the selected roles. |
Post Status
Choose the status of posts to query.
Details: Select one or several statuses. Available for Post Query. Default: Published.
Options:
| Status | Description |
|---|---|
| Published | Publicly available posts. |
| Pending | Posts awaiting review. |
| Draft | Unpublished posts. |
| Private | Posts visible only to logged-in users with permission. |
| Trashed | Posts moved to the trash. |
Order By
Define the field used to order results.
Details: Select the criterion for ordering. Available for Post, User and Taxonomy queries. Default: Date.
Options:
| Order By | Description |
|---|---|
| Date | Sort by publication date. |
| Last Modified | Sort by last modified date. |
| Random | Sort randomly. |
| Comment Count | Sort by number of comments. |
| Title | Sort alphabetically by title. |
| Post ID | Sort by ID. |
| Author | Sort by author. |
| Menu Order | Sort by the menu order set on each post. |
| Relevance | Sort by how well posts match a search. |
| Custom Field | Sort by a custom field value. |
| Custom Field (Numeric) | Sort by a numeric custom field value. |
Field Key
Specify the custom field meta key for ordering.
Details: Enter the meta key (e.g., _price for WooCommerce products). Available when Order By is Custom Field or Custom Field (Numeric).
Order
Define the sorting direction.
Details: Choose ascending or descending order. Default: Descending.
Options:
| Order | Description |
|---|---|
| Descending | Highest first: newest first, or Z–A. This is the default. |
| Ascending | Lowest first: oldest first, or A–Z. |
Offset
Skip a number of posts at the start of the list.
Details: Set the number of posts to skip, from 0 to 100. Default: 0.
Post Query Filters
Narrow a Post Query by terms and specific posts.
Details: Available for Post Query. For each taxonomy of the selected post type, choose Include or to exclude, then pick the terms. Use Include Posts and Exclude Posts to pick individual posts.
Options:
| Setting | Description |
|---|---|
| Sticky Posts | Places WordPress sticky posts first in the list. |
| Related Posts | Lists posts that share a term with the current post, excluding the current post. Use it in single post templates. Posts use their categories. For other post types, choose the taxonomy with Select Related Taxonomy. |
| Pinned Posts | Lists only the posts the visitor has pinned. Requires the Bookmark content type. See Bookmark Options. |
Query ID
Give the widget’s query a unique ID.
Details: The ID lets you modify the query in PHP with the bpfwe/query/{query_id} action. See the Custom Query Guide.
Nothing Found Message
Set the message shown when there are no results.
Details: Default: “It seems we can’t find what you’re looking for.”
Carousel Settings
Configure the carousel layout and behavior.
Details: Customize breakpoints, slide visibility, navigation, and effects for the carousel. Available when “Carousel” is selected under Layout.
Options:
| Setting | Purpose | Details |
|---|---|---|
| Trigger Breakpoint | Set the screen size where the carousel is active. | The carousel is active at and below this breakpoint. Above it, the posts show as a normal grid. Leave empty to show the carousel on all screen sizes. |
| Slides Per View | Define the number of visible slides. | Set 1 to 8.5 slides, in steps of 0.5 for partial slides. Responsive. Default: 3 on desktop and tablet, 1 on mobile. |
| Slides to Scroll | Set the number of slides to move at a time. | Choose 1 to 8 slides. Responsive. |
| Slide Layout | Choose the direction slides move. | Horizontal (default) or Vertical. |
| Slide Gap | Define the space between slides. | Set the gap from 0 to 60 pixels. Default: 20. |
| Adaptive Height | Adjust the carousel height to the current slide. | On by default. |
| Slider Height | Set a fixed height for the carousel. | Choose a height in pixels or viewport height (vh). Default: 500px. Available when Adaptive Height is off. |
| Arrow | Show or hide the navigation arrows. | On by default. |
| Slide to Clicked Slide | Move to a slide when it is clicked. | Off by default. |
| Pagination | Show or hide the pagination indicators. | On by default. The indicators are shown below the carousel. |
| Pagination Type | Choose the pagination style. | Bullets (small dots, default), Fraction (current/total slide numbers) or Progressbar. Available when Pagination is on. |
| Custom Navigation | Control the carousel from other widgets on the page. | When on, add the class WIDGETID-slide-N to any widget on the page to jump to slide N. Use WIDGETID-slide-prev and WIDGETID-slide-next for the previous and next slide. |
| Autoplay | Turn automatic slide transitions on or off. | On by default. |
| Marquee Mode | Scroll slides continuously. | Slides move in a steady, endless scroll instead of pausing between slides. Touch move is turned off. Available when Autoplay is on. Animation Delay and Infinite Loop don’t apply in this mode. |
| Pause on Hover | Pause autoplay when visitors hover over the carousel. | On by default. |
| Enable Touch Move | Allow swipe navigation. | On by default. |
| Enable Mousewheel | Allow mousewheel navigation. | Off by default. |
| Transition Effect | Choose the transition effect. | Slide (default) or Fade. |
| Animation Speed | Set the duration of the slide transition. | In milliseconds. Default: 1200. |
| Animation Delay | Set the time between autoplay transitions. | In milliseconds. Default: 4000. Not available in Marquee Mode. |
| Infinite Loop | Loop the slides continuously. | On by default. Not available in Marquee Mode. |
| Center Mode | Center the active slide. | On by default. |
| Centered Slide Bounds | Keep centered slides within the carousel edges. | Off by default. |
| Lazy Load | Load slide images only when they come into view. | Off by default. Not recommended for carousels above the fold. |
| Apply Parallax | Enable a parallax effect for slides. | Turn it on, then add the required data attributes to the slide widgets, as detailed in the Swiper API documentation at https://swiperjs.com/swiper-api#parallax. |
| Use Featured Image as BG | Show each post’s featured image as the slide background. | Off by default. Options: Hide the Feature Image removes the normal image so only the background shows, CSS filters can be applied to the background, and Background Class gives you a class to target it. |
| Synchronize Carousel | Link two carousels so they move together. | Add the class sync-sliders to at least two post widgets on the same page. |
Pagination Settings
Pagination
Choose how visitors move through the results.
Details: Select the type of pagination. Default: None. The number of posts per page is set by Posts Per Page.
Options:
| Type | Description |
|---|---|
| None | No pagination. |
| Numbers | Shows numbered page links. |
| Numbers + Previous/Next | Shows numbered page links with previous and next links. |
| Load More Button | Adds a button that loads the next posts below the current ones. |
| Infinite | Loads the next posts automatically as the visitor scrolls. |
Max. Pages
Limit the number of pages.
Details: Set the maximum number of pages visitors can reach. Use -1 for no limit. Default: -1. Not available in the Carousel layout.
Pagination (Carousel Layout)
Choose the pagination for the Carousel layout.
Details: In the Carousel layout, pagination can be None, Numbers, or Numbers + Previous/Next. Turn on Display on Carousel to show the pagination controls with the carousel.
Scroll to Top
Scroll the page after changing pages.
Details: When on, the page scrolls to the top of the widget when a visitor loads another page. Available for Numbers, Numbers + Previous/Next and Load More Button. Default: off.
Hide Spinner
Hide the loading spinner.
Details: Available when Pagination is set to Infinite.
Scroll Threshold
Set how early the next posts load.
Details: Available when Pagination is set to Infinite. Enter a value in pixels or percent. A negative value loads posts sooner, a positive value later. Default: 0.
Additional Options
Open Links in New Tab
Open post links in a new browser tab.
Details: Not available for the Template Grid skin.
External URL
Replace all post links with one URL.
Details: Paste a URL or use a custom field. Turn on Use Post URL as Fallback to use the post’s own link when the external URL is empty.
Refresh Background Images
Fix dynamic background images that show the wrong image after filtering.
Details: Off by default. Turn it on if a dynamic background image shows the wrong picture after a filter is applied. Developers can also enable it with the bpfwe_enable_background_image_resolution filter.
Include / Exclude Posts by ID
Include or exclude specific posts by their IDs.
Details: Enter a comma-separated list of IDs. These fields replace the Include Posts and Exclude Posts pickers in the Query section.