# Product grid

### Section Overview

The Product grid section displays a collection of products in a customizable grid layout with optional header content and content blocks. It allows merchants to showcase products with flexible layout options including split-view layouts and grid configurations.

#### Common Use Cases

* Featuring products from a specific collection on homepage or landing pages
* Creating a product showcase with accompanying promotional content
* Building category pages with filterable product displays
* Creating a featured products section with supplementary content blocks

#### Usage Tips

* The split layout option works best when you have compelling header content to display alongside products
* For mobile displays, consider using a single column layout for better product visibility
* Customize grid density based on the size and complexity of your product images
* Use the content block strategically to add context or promotional messaging within the product grid
* Ensure your collection has enough products to fill the grid properly; consider product count settings based on available products

#### Metafields on product cards

Grid layouts use the theme’s standard product cards. **Table details** under **Theme settings → Product cards** does not add metafields to grid cards; it applies to list and table (row) layouts only. For which metafields appear on grid cards without code, how grid differs from list or table, and workarounds, see [Metafields on product cards](/keystone/guides/products/metafields-on-product-cards.md).

### Section Settings

| Setting              | Description                                                    |
| -------------------- | -------------------------------------------------------------- |
| Collection           | Select which product collection to display                     |
| Products count       | Set the maximum number of products to display                  |
| Heading              | Main heading for the section                                   |
| Content              | Rich text content displayed in the section header              |
| Button label         | Text for the optional button                                   |
| Button URL           | URL destination for the button                                 |
| Top spacing          | Amount of spacing above section (in pixels)                    |
| Bottom spacing       | Amount of spacing below section (in pixels)                    |
| Color scheme         | Background and text color theme for the section                |
| Border color         | Color of the section border                                    |
| Border position      | Position of borders around the section                         |
| Desktop columns      | Number of product columns on desktop devices                   |
| Mobile columns       | Number of product columns on mobile devices                    |
| Horizontal alignment | Horizontal alignment of section content                        |
| Enable margin        | Enable horizontal margin based on theme settings               |
| Enable split         | Enable split layout with header on left and products on right  |
| Visibility           | Device visibility settings (all, mobile-only, or desktop-only) |

### Block Settings

#### Content Block

This block adds a content component within the product grid that can include text, images, or video. Limited to 1 per section.

| Setting              | Description                                          |
| -------------------- | ---------------------------------------------------- |
| Heading              | Block heading text                                   |
| Content              | Rich text content for the block                      |
| Button label         | Text for the optional button                         |
| URL                  | URL destination for the button                       |
| Image                | Main image for the content block                     |
| Background image     | Background image for the content block               |
| Video                | Video file for the content block                     |
| Enable autoplay      | Auto-play video when in view                         |
| Enable mute toggle   | Show mute/unmute button for video                    |
| Enable loop          | Loop video playback                                  |
| Minimum height       | Minimum height of the content block (in pixels)      |
| Enable padding       | Add internal padding to the content block            |
| Color scheme         | Background and text color theme for the block        |
| Text color           | Force specific text color regardless of color scheme |
| Border color         | Color of the block border                            |
| Button style         | Style and color of the button                        |
| Enable gradient      | Add gradient effect to background                    |
| Vertical alignment   | Vertical alignment of content within block           |
| Horizontal alignment | Horizontal alignment of content within block         |
| Text position        | Position of text relative to media (above or below)  |


---

# Agent Instructions: 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:

```
GET https://help.brickspacelab.com/keystone/sections/products-and-collections/product-grid.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.