Home » Guides » Wordpress » Wordpress Fse Cpt Archive Template
📌 Pin 🔗 Copy Link 📋 Copy Markdown ⬇️ Download
2 min read

Creating a CPT Archive Template (Portfolio Grid)

When you register a Custom Post Type (CPT) with 'has_archive' => true, WordPress creates a URL (e.g., your-site.com/portfolio/) to display all items of that type.

To control the layout of this page, you need to create a specific archive template.

1. The Template Hierarchy

WordPress uses a "fallback" system to find the right template. For a CPT named portfolio, it looks for files in this order:

  1. archive-portfolio.html: The specific template for the Portfolio archive. This is what we will create.
  2. archive.html: The generic template for any archive (categories, tags, etc.).
  3. index.html: The final fallback for everything.

2. Creating the Template File

In your theme's templates/ directory, create a new file named archive-portfolio.html.

The Block Structure

The core of an archive template is a Query Loop block with the inherit property set to true. This tells the block to use the main WordPress query for the page, which on this URL, is already configured to fetch all your "Portfolio" posts.

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->

<!-- wp:group {"tagName":"main","style":{"spacing":{"padding":{"top":"var:preset|spacing|50","bottom":"var:preset|spacing|50"}}},"layout":{"type":"constrained"}} -->
<main class="wp-block-group" style="padding-top:var(--wp--preset--spacing--50);padding-bottom:var(--wp--preset--spacing--50)">

    <!-- wp:query-title {"type":"archive","textAlign":"center","style":{"typography":{"fontSize":"3rem"}}} /-->

    <!-- wp:paragraph {"align":"center"} -->
    <p class="has-text-align-center">Check out our latest work.</p>
    <!-- /wp:paragraph -->

    <!-- 
        The main query loop. 
        "inherit": true is the key. It automatically uses the query for this archive page.
    -->
    <!-- wp:query {"queryId":1,"query":{"perPage":9,"pages":0,"offset":0,"postType":"post","order":"desc","orderBy":"date","author":"","search":"","exclude":[],"sticky":"","inherit":true}} -->
    <div class="wp-block-query">

        <!-- The Post Template, set to a 3-column grid -->
        <!-- wp:post-template {"style":{"spacing":{"blockGap":"var:preset|spacing|40"}},"layout":{"type":"grid","columnCount":3}} -->

            <!-- wp:group {"layout":{"type":"default"}} -->
            <div class="wp-block-group">
                <!-- wp:post-featured-image {"isLink":true,"aspectRatio":"4/3"} /-->
                <!-- wp:post-title {"isLink":true,"style":{"spacing":{"margin":{"top":"var:preset|spacing|20"}}}} /-->
            </div>
            <!-- /wp:group -->

        <!-- /wp:post-template -->

        <!-- wp:query-pagination {"layout":{"type":"flex","justifyContent":"center"}} -->
            <!-- wp:query-pagination-previous /-->
            <!-- wp:query-pagination-numbers /-->
            <!-- wp:query-pagination-next /-->
        <!-- /wp:query-pagination -->

    </div>
    <!-- /wp:query -->

</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

3. Creating Visually in the Site Editor

You can also build this without touching code:

  1. Go to Appearance > Editor > Templates.
  2. Click Add New (the + icon).
  3. Select Archive.
  4. From the list, choose Archive: Projects. WordPress knows this CPT exists and offers it as an option.
  5. Build the layout using the blocks as described above.
  6. When you save, WordPress will create the archive-portfolio.html file for you.
Created: March 19, 2026 • Last Modified: March 19, 2026