> For the complete documentation index, see [llms.txt](https://docs.northcommerce.com/north-commerce/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.northcommerce.com/north-commerce/blocks/product-query.md).

# Product Query

The Product Query block is your shop grid. It shows many products at once so customers can browse, filter, and add one to the cart.

This is the block version of the older product collections.

{% hint style="info" %}
If you want **one product on its own page**, use Product. If you want products in a **horizontal slider**, use [Collection Slider](/north-commerce/blocks/collection-slider.md). If you want a “You may also like” strip, use [Product Recommendations](/north-commerce/blocks/product-recommendations.md).
{% endhint %}

## Before you start

1. North Commerce and North Commerce Blocks are installed and turned on
2. You have at least one product. See Create a product if you still need one

## Add it to a page

North Commerce already creates a shop / collections page for you. You can also put this on any page.

1. In WordPress go to **Pages**
2. Open your shop page, or click **Add New Page**
3. Click the **+** button
4. Search for **Product Query**
5. Click it once

![Search for Product Query in the block inserter](https://3754649969-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FD2GW0FgHldEZwt1FAF7r%2Fuploads%2F0FPFMgYWo36XTJIgNZ48%2Feditor-add-product-query.jpg?alt=media)

The sort control, filters, product cards, and a **Load More** button all come with it.

6. Click the Product Query block so it is selected
7. In the right-hand sidebar, pick which products show (see below)
8. Click **Update** / **Publish**

{% hint style="success" %}
You only need one Product Query block on the page.
{% endhint %}

## Pick which products show

Click the Product Query block. In the sidebar you will see **Query Source**.

* **Manual** — you pick the categories. Under **Filters**, use **Select Categories**. If you pick more than one, **Compare Multiple Filters With** can be **OR** (either category) or **AND** (must be in all of them).
* **Automatic** — on a category or tag page, it shows that group. On a regular page, it shows all products.

You can also set:

* **Items to show** — how many cards load at first (1–24)
* **Sort** — Newest, Name A–Z or Z–A, Price low to high or high to low
* **New badge count** — how many of the newest products get flagged as New
* **Accent color** — the highlight color for the filters

![Product Query settings in the sidebar](https://3754649969-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FD2GW0FgHldEZwt1FAF7r%2Fuploads%2Fcad5NzHnyFecK237gnP5%2Feditor-product-query-settings.jpg?alt=media)

## What comes in the block

You can leave everything as-is.

### Product template

This is one product card. The grid repeats it for every product.

Click it to set **Desktop columns** (2–4) and **Mobile columns** (1–2), plus the **Gap**.

You can change what is on the card: photo, title, price, and so on. Those pieces are the same ones on the Product page.

### Product Query Filters

Lets customers narrow the grid. No page reload.

Click it to choose:

* **Placement** — **sidebar** (filters stay on the side) or **top** (a **Filters** button that opens a panel)
* What to show: **Category**, **Price**, **Color**, **Size**, **Availability**
* Whether to show the active chips and the product count

The button label starts as **Filters**. You can edit that text on the block.

### Product Sort

Lets customers change the order. In the sidebar:

* **Display Type** — **Dropdown** or **Buttons**
* **Show Label** — the words next to it (starts as “Sort by:”)

### Load More button

Adds the next batch of products on the same page. You can change the button text (it starts as **Load More**).

### Pagination

Page numbers (1, 2, 3) and next / previous. This does **not** come in by default. Click inside the Product Query block, click **+**, and search for **Pagination**.

You can turn **Show Next/Prev buttons** and **Show Numeric buttons** on or off.

{% hint style="info" %}
Use **Load More** or **Pagination**, not both. Load More keeps people on one long page. Pagination splits the shop into pages.
{% endhint %}

### Product Quick Add

A button on the card. On hover (or always), the customer can add the product without opening the product page. If the product has options, a small picker opens first.

In the sidebar you can set **Reveal** (**hover** or **always**) and **Placement** (**overlay** on the photo, or **inline** under the card). The label starts as **Quick add**.

### Product Swatches

Color dots on the card. Only shows if that product has a Color option.

In the sidebar: **Shape** (**Dots** or **Squares**) and **Max swatches**.

### Product Badge

The NEW / SALE label on the card. See Product.

## What your customer will do

1. Browse the grid
2. Sort or filter if you left those on
3. Click a product to open its page, or use **Quick add** if you left that on
4. Click **Load More** (or a page number) if there are more products

## Make sure it works

Open the page in a new browser tab, as if you were the customer.

1. You should see product cards with names and prices
2. If you set a category, only those products should show
3. Click **Load More** (or a page number) if you have more products than **Items to show**
4. Click a card. It should open the product page.

![A live shop grid with Product Query](https://3754649969-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FD2GW0FgHldEZwt1FAF7r%2Fuploads%2FQs9G46t6BISjdm9fZO8j%2Flive-product-query.jpg?alt=media)

## If something looks wrong

* **No products.** You have no products yet, or **Manual** is on and the category you picked has none.
* **Wrong products.** Click the block. Check **Query Source** and **Select Categories**.
* **Filters do nothing.** **Product Query Filters** was deleted, or every filter type is turned off.
* **Cards look empty.** The **Product template** is missing a title, photo, or price. Click the card and add those pieces back.

SEE ALSO: Product · [Collection Slider](/north-commerce/blocks/collection-slider.md) · [Product Recommendations](/north-commerce/blocks/product-recommendations.md) · Create a product