Post List

Display posts with query builder and customizable templates

Pro Feature

Post List is a premium element that requires a Pro or Agency license. Activate your license to use this element.

Overview

The Post List element dynamically displays WordPress posts, pages, or custom post types. It includes a powerful query builder for filtering by taxonomy, date, and custom fields, plus flexible display options including grid layouts and carousel modes.

Each post in the list is rendered using an HTML template with placeholders that are replaced with actual post data. This gives you full control over the card layout, including which fields to display and how they're styled.

The element renders as a <div> container with configurable classes. Default classes include grid gap-6 for a grid layout. Switch to carousel mode for a horizontal scrolling experience.

Settings

Query Settings

Configure which posts to display:

Setting Description Default
Post Type The post type to query. Options include post, page, or any registered custom post type (e.g., product, portfolio). post
Taxonomies Filter by taxonomy terms. An object mapping taxonomy names to term IDs or slugs (e.g., {"category": [5, 8]}). {} (empty)
Tags Filter by specific tags. Array of tag IDs or slugs. [] (empty)
Limit Maximum number of posts to display. Use -1 for unlimited (not recommended for performance). 6
Offset Number of posts to skip before displaying. Useful for excluding the first N posts (e.g., when showing them elsewhere). 0
Order By Field to sort posts by. Options: date, title, menu_order, rand, comment_count, modified. date
Order Sort direction. DESC for newest/highest first, ASC for oldest/lowest first. DESC

Display Settings

Configure how posts are presented:

Setting Description Default
Display Type Layout mode. normal for grid layout, carousel for horizontal sliding. normal
Container Class CSS classes for the posts container. For grids, use grid grid-cols-3 gap-6. Adjust columns per breakpoint with responsive classes. grid gap-6
Setting Description Default
Slides Per View Number of posts visible at once in the carousel. 3
Autoplay Automatically advance slides. false
Show Navigation Display prev/next arrow buttons. true

Empty State Settings

Setting Description Default
Empty Behavior What to show when no posts match the query. message displays the Empty Message, hide hides the element entirely. message
Empty Message Text displayed when no posts are found. No posts found.

Template Placeholders

The Post List uses an HTML template with placeholders that are replaced with post data. Available placeholders:

Placeholder Description
{{title}} Post title
{{excerpt}} Post excerpt (auto-generated from content if not set)
{{content}} Full post content
{{thumbnail}} Featured image URL
{{permalink}} Post URL
{{date}} Publication date
{{author}} Author display name
{{categories}} Comma-separated category names

Examples

Basic Blog Grid

A 3-column grid of recent blog posts with featured images, titles, and excerpts.

<!-- Query Settings: Post Type: post, Limit: 6, Order By: date -->
<!-- Display Settings: Container Class: grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6 -->

<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
  <!-- Template for each post -->
  <article class="bg-white rounded-lg shadow overflow-hidden">
    <img src="{{thumbnail}}" alt="{{title}}" class="w-full h-48 object-cover">
    <div class="p-4">
      <span class="text-sm text-gray-500">{{date}}</span>
      <h3 class="text-lg font-semibold mt-1">
        <a href="{{permalink}}" class="hover:text-primary">{{title}}</a>
      </h3>
      <p class="text-gray-600 mt-2">{{excerpt}}</p>
    </div>
  </article>
</div>

A horizontal carousel showing featured posts with autoplay.

<!-- Query Settings: Post Type: post, Taxonomies: {"category": ["featured"]}, Limit: 8 -->
<!-- Display Settings: Display Type: carousel, Autoplay: true -->

<div class="relative overflow-hidden">
  <div class="flex gap-4 transition-transform">
    <!-- Each post card -->
    <article class="flex-shrink-0 w-80 bg-white rounded-lg shadow">
      <img src="{{thumbnail}}" alt="{{title}}" class="w-full h-40 object-cover rounded-t-lg">
      <div class="p-4">
        <h3 class="font-semibold">
          <a href="{{permalink}}">{{title}}</a>
        </h3>
        <p class="text-sm text-gray-500 mt-1">By {{author}}</p>
      </div>
    </article>
  </div>

  <!-- Navigation arrows -->
  <button class="absolute left-2 top-1/2 -translate-y-1/2 bg-white shadow rounded-full p-2">←</button>
  <button class="absolute right-2 top-1/2 -translate-y-1/2 bg-white shadow rounded-full p-2">→</button>
</div>

Custom Post Type List

Display a custom post type (e.g., portfolio projects) with taxonomy filtering.

<!-- Query Settings: -->
<!-- Post Type: portfolio -->
<!-- Taxonomies: {"portfolio_category": ["web-design"]} -->
<!-- Order By: menu_order -->
<!-- Order: ASC -->
<!-- Limit: 12 -->

<div class="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4">
  <a href="{{permalink}}" class="group relative aspect-square overflow-hidden rounded-lg">
    <img src="{{thumbnail}}" alt="{{title}}" class="w-full h-full object-cover group-hover:scale-105 transition-transform">
    <div class="absolute inset-0 bg-black/50 opacity-0 group-hover:opacity-100 transition-opacity flex items-center justify-center">
      <h3 class="text-white font-semibold text-lg">{{title}}</h3>
    </div>
  </a>
</div>
Performance Tip

Keep the Limit setting reasonable (6-12 posts) for initial page loads. For larger archives, consider pagination or "Load More" patterns using the Offset setting.

Next Steps