Posted on — Last updated on February 18, 2024

How to display a grid of popular posts in WordPress

Learn how to make a fully customizable grid of popular posts with thumbnails in WordPress.

One of the strongest points of the WordPress Popular Posts plugin lies in its customization options. If you’re familiar with CSS/HTML, the possibilities are endless!

For those of you who don’t know how to code though it’s a completely different story. Understandably, I often get asked questions like:

  • How can I make a grid of popular posts?
  • I’d like to show a grid of thumbnails with post titles using WordPress Popular Posts, can it be done?
  • I want to display my popular posts in a grid layout, how can I do that?

… and a bunch of other similar questions, you get the idea.

In this article, I’ll show you how to create a responsive grid of popular posts with thumbnails.

Before we start

Oh, by the way, here’s what we’re trying to accomplish (yes, this is a live popular posts grid):

Neat, huh?

Ready? Let’s go!

Part 1: The HTML Markup

Our first step would be, of course, to modify’s WPP’s HTML markup so we can then apply some CSS sorcery on it to make our popular posts list look like a nice posts grid.

If you’re using the WordPress Popular Posts block please follow these steps (instructions for the wpp_get_mostpopular() template tag and the [wpp] shortcode are included below):

  1. Insert a WordPress Popular Posts block into your post / page via the block editor.
  2. Set Show Up to X Posts to 3 (or your desired number of posts.)
  3. Under Posts settings, tick the Display post thumbnail checkbox and set the desired width and height of the thumbnails (for this tutorial I’ll be using 225×135 but feel free to use any size you want).
  4. Under HTML Markup Settings, tick the Use custom HTML markup checkbox.
  5. Under Before / after Popular Posts, set the first field to the following:
    <ul class="wpp-grid">
  6. Next, change Post HTML Markup to:
      <li>{thumb} {title}</li>
  7. Finally, save changes.

And that’s it! Our popular Posts block is ready to be turned into a Popular Posts grid.

If you’re using the wpp_get_mostpopular() template tag

Now, to accomplish the same thing with the wpp_get_mostpopular() template tag we’ll be using the parameters wpp_start and post_html, where the former sets the opening HTML tag of our popular posts grid (see step 4 above) and the latter the HTML markup of each post (see step 5 above):

if ( function_exists('wpp_get_mostpopular') ) {

    $args = array(
        'range' => 'last7days',
        'post_type' => 'post',
        'limit' => 3, // Sets the number of posts to display
        'thumbnail_width' => 225,
        'thumbnail_height' => 135,
        'wpp_start' => '<ul class="wpp-grid">',
        'post_html' => '<li>{thumb}{title}</li>'
    wpp_get_mostpopular( $args );


Check the Parameters documentation for more details.

If you’re using the [wpp] shortcode

And this is the [wpp] shortcode version, which uses the exact same set of parameters as the wpp_get_mostpopular() template tag:

[wpp range='last7days' post_type='post' limit=3 thumbnail_width=225 thumbnail_height=135 wpp_start='<ul class="wpp-grid">' post_html='<li>{thumb}{title}</li>']

One note though: if you’re using the Block Editor make sure to use the Shortcode block to insert your [wpp] shortcode into your sidebar/post/page to make sure that the WordPress editor doesn’t break it since you’re using HTML tags with it.

Part 2: Styling the grid

Now that the HTML markup is ready, all that’s left to do is to style our popular posts list into an actual grid.

Add the following CSS styles to your theme’s stylesheet:

/** By default, our grid will fit 
 the entire width of its container (mobile-first approach) */
.wpp-grid {
  margin: 1.35rem 0;
  padding: 0;

  .wpp-grid li {
    list-style: none;
    margin: 0 0 1.5rem;
    padding: 0;
  .wpp-grid li:last-child {
    margin: 0;
    .wpp-grid li .wpp-thumbnail {
      display: block;
      width: 100%;
      height: auto;
      border-radius: 5px;
    .wpp-post-title {
      display: block;
      margin-top: 0.8em;
      font-size: 1.1rem;
      font-weight: bold;
      line-height: 1.3;
      text-align: center;

/** This is where the magic happens: 
 on larger screens our popular posts list 
 will be displayed as a grid. */

@media only screen and (min-width: 481px) {
  .wpp-grid {
    display: grid;
    grid-template-columns: 1fr 1fr; /* Two-columns */
    grid-gap: 1.5rem;

    .wpp-grid li {
      margin: 0;

@media only screen and (min-width: 768px) {
  .wpp-grid {
    grid-template-columns: 1fr 1fr 1fr; /* Three-columns */

Reload your browser (you might need to do a hard-refresh) and if everything went fine you should be seeing a nice popular posts grid now.

Questions? Suggestions? Feel free to leave a comment below!