---
tags:
  - wordpress
  - fse
  - templates
  - archive
  - cpt
  - portfolio
title: Creating a CPT Archive Template (Portfolio Grid)
---

# 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.

```html
<!-- 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.