> For the complete documentation index, see [llms.txt](https://uxsmart.gitbook.io/velare/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://uxsmart.gitbook.io/velare/customize-your-pages/collection-page/page-template-sections/product-grid.md).

# Product grid

**Product grid** is the listing at the heart of every collection page. It shows the products in the category as a grid of cards and gives customers the filters, the sorting menu, and the pagination they use to work through a large catalogue. It is where a browsing visitor decides which product is worth opening.

Two settings here do most of the work for sales: how many products load before a customer has to act, and whether filtering is available at all. You can also drop promotion tiles among the products to advertise an offer without interrupting the browse.

<figure><img src="/files/IsvyjegEnoBtCk2aZx00" alt=""><figcaption></figcaption></figure>

## How to add a Product grid section? <a href="#how-to-add" id="how-to-add"></a>

{% hint style="success" %}
**Steps:**

1. Go to **Online Store > Themes > Customize**.
2. Open the template selector and select **Collections**, then **Default collection**.
3. In the left sidebar, click **Add section** and choose **Product grid**.
4. Adjust the settings, then click **Save**.
   {% endhint %}

*Result:* the products of the sample collection appear in the preview, laid out with the number of columns and the pagination style you chose.

## How to customize your Product grid section <a href="#how-to-customize" id="how-to-customize"></a>

### General Settings <a href="#general-settings" id="general-settings"></a>

<figure><img src="/files/WTHsJpCvmJG9cav8euYy" alt=""><figcaption></figcaption></figure>

<table data-full-width="false"><thead><tr><th>Setting</th><th>Description</th></tr></thead><tbody><tr><td><strong>Section width</strong></td><td><p>How far the grid stretches across the screen.</p><ul><li><strong>Stretch width</strong>: the products run close to the screen edges whatever the display size, which fits more per row.</li><li><strong>Fixed width</strong>: the grid lines up with the rest of your pages, using the width set in <strong>Theme settings > Layout</strong>.</li><li><strong>Full width</strong>: the grid fills the whole screen and rescales itself to fit it.</li></ul></td></tr><tr><td><strong>Items to show per page</strong></td><td>How many products load before the customer has to click or scroll for more. Minimum: 4. Maximum: 24. A higher number lets people browse freely, a lower one keeps the page fast.</td></tr><tr><td><strong>Columns per row on desktop</strong></td><td>How many products stand side by side on a desktop screen. Minimum: 2. Maximum: 5. Fewer columns give bigger photos, more columns show more of the category at a glance.</td></tr><tr><td><strong>Column gap</strong></td><td><p>How much air sits between the products.</p><ul><li><strong>No gap</strong>: the cards touch, giving a dense catalogue feel.</li><li><strong>Small</strong></li><li><strong>Medium</strong></li><li><strong>Large</strong>: each product gets room to breathe, which suits a small curated range.</li></ul></td></tr></tbody></table>

**Pagination type**

How customers reach the rest of the collection once the first products have loaded. **Page number** suits large catalogues where people want to jump ahead and keep their place, **Load more button** puts the customer in control of each extra batch, and **Infinite scroll** keeps browsing uninterrupted but makes the footer hard to reach.

{% tabs %}
{% tab title="Page number" %}

<figure><img src="/files/bcgFD66zjXcqn3CW3Hjq" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Load more button" %}

<figure><img src="/files/JCyzUtFdWAFiH7oZw0Cs" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Infinite scroll" %}

<figure><img src="/files/XZ6V4NyNSzmbfKk5jwBv" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

### Filtering and sorting <a href="#filtering-and-sorting" id="filtering-and-sorting"></a>

<figure><img src="/files/wQJw7dFsCmEOfu4rQOmL" alt=""><figcaption></figcaption></figure>

<table data-full-width="false"><thead><tr><th>Setting</th><th>Description</th></tr></thead><tbody><tr><td><strong>Enable sorting</strong></td><td>Gives customers the menu that reorders the collection, for example by price or by newest. Worth keeping on for any category with more than a screen of products.</td></tr><tr><td><strong>Enable filtering</strong></td><td>Shows the filters you configured in your Shopify admin, so a customer can cut a large category down to the size, colour, or price range they want instead of scrolling past everything.</td></tr><tr><td><strong>Show product counts</strong></td><td>Puts the number of matching products next to each filter option, which tells customers whether a choice is worth making before they click it.</td></tr><tr><td><strong>Desktop filter layout</strong></td><td><p>How the filters are presented on a desktop screen.</p><ul><li><strong>Vertical</strong>: the filters sit in a column beside the product grid and stay visible, so shoppers can refine without an extra click. Best when your category has room to spare on wide screens.</li><li><strong>Drawer</strong>: the filters stay behind a button and slide out in a panel when clicked, keeping the grid full width. Good for a cleaner look or when you have a long list of filter options.</li></ul></td></tr></tbody></table>

{% hint style="info" %}
**Enable filtering** only has something to show once filters exist in your store, and filters are created with the [Shopify Search & Discovery](https://apps.shopify.com/search-and-discovery) app rather than in the theme.

The same app also decides your search results and your product recommendations, so installing it gives you control over how customers find products across the whole store, not just in this grid.

Read [how to customize filters using the app.](https://help.shopify.com/en/manual/online-store/search-and-discovery/filters)
{% endhint %}

### Section padding <a href="#section-padding" id="section-padding"></a>

| Setting    | Description                                                                                                    |
| ---------- | -------------------------------------------------------------------------------------------------------------- |
| **Top**    | Adds space above the grid. Increase it when the first row of products sits too close to the collection banner. |
| **Bottom** | Adds space under the grid, separating the last row from the footer or from any section you added below.        |

### Block settings <a href="#block-settings" id="block-settings"></a>

**Promotion**

A tile that takes the place of a product in the grid, carrying an image, a message, and a button. Because it sits inside the listing rather than above it, customers meet the offer while they are already choosing.

<figure><img src="/files/OtMaYcCoWEagy5JubKUJ" alt=""><figcaption></figcaption></figure>

| Text                   | Description                                                                                                                                                                             |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Color scheme**       | The background and text colours of the tile, taken from **Theme settings > Colors**. Choose a scheme that stands apart from the product cards, so the tile is not mistaken for an item. |
| **Image**              | The picture filling the tile ***(330px x 550px recommended)***. Use that size so the tile matches the height of the product cards beside it.                                            |
| **Subheading**         | A short line above the main message, usually the offer in a few words.                                                                                                                  |
| **Heading**            | The message itself, the part customers read while scanning the grid.                                                                                                                    |
| **Description**        | A sentence explaining the offer, for example who qualifies or when it ends.                                                                                                             |
| **Button label**       | The wording on the button. Say where it leads, for example `Shop the sale`.                                                                                                             |
| **Link**               | The destination that button opens, typically the collection or page holding the offer.                                                                                                  |
| **Promotion position** | Which slot in the grid the tile occupies. If the collection holds fewer products than that number, the tile is not shown at all, so keep it low for small categories.                   |

**Shop by step**

A guided tile placed in the grid that points customers to the next stage of a purchase, for example a matching item or a follow up category.

| Setting          | Description                                                                                                              |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Image**        | The picture filling the tile ***(337px x 200px recommended)***. Use that size so it sits neatly among the product cards. |
| **Heading**      | The line customers read first, naming the step you want them to take.                                                    |
| **Description**  | A sentence explaining why that step is worth taking.                                                                     |
| **Button label** | The wording on the button, phrased as the action itself.                                                                 |
| **Link**         | The page the button opens.                                                                                               |

### Impact outside the theme editor <a href="#impact-outside" id="impact-outside"></a>

The grid applies to every collection using the **Default collection** template. The products it shows and the order they start in come from the collection itself in **Shopify admin > Products > Collections**, and the filter options come from the Search & Discovery app, not from the theme. Each card follows the shared rules in **Theme settings > Product cards**, including image ratio, badges, swatches, and quick add. A high value for **Items to show per page** with infinite scroll makes long collections heavier to load on mobile connections.

### Related pages <a href="#related-pages" id="related-pages"></a>

* [Collection banner](/velare/customize-your-pages/collection-page/page-template-sections/collection-banner.md): the header shown above this grid
* [Product cards](/velare/customize-your-pages/product-cards.md): the presentation rules for every card in the grid
* [Badges](/velare/customize-your-pages/badges.md): the sale, new, and sold out labels on those cards
* [Custom product badge](/velare/buy-and-install/create-required-metafields/metafields/custom-product-badge.md): your own badge text on a single product
* [Quickview](/velare/customize-your-pages/overlay-group/quickview.md): the popup opened by quick shop from the grid
* [Product page](/velare/customize-your-pages/product-page.md): where a customer lands after clicking a card


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://uxsmart.gitbook.io/velare/customize-your-pages/collection-page/page-template-sections/product-grid.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.