> For the complete documentation index, see [llms.txt](https://ursus-ecom.gitbook.io/arctos-theme/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ursus-ecom.gitbook.io/arctos-theme/blocks/collections-and-products/product-list.md).

# Product list

Show selected products or a collection as responsive product cards, grids, and carousels.

The **Product list** block displays product cards from a selected collection or from a manual list of products. Use it to feature best sellers, new arrivals, seasonal edits, sale products, or a compact product carousel inside a compatible section or container.

Product list controls the product source, item count, grid or carousel behavior, color scheme, and spacing. Each product is rendered with a built-in **Product card**, where you can override the global product card settings for this block.

### 1. What you can do

* Select products from a Shopify collection
* Choose specific products manually
* Show 2-15 products
* Display product cards in a grid or carousel
* Turn a desktop grid into a carousel on mobile
* Add autoplay, infinite loop, hint, control buttons, and pagination for carousel layouts
* Customize product image shape, corners, background color, and hover behavior
* Customize product information, color swatches, badges, and quick actions for this list
* Adjust color scheme and padding around the complete Product list block

### 2. Understanding the Product list structure

Product list uses one built-in Product card for every product that appears, supports an optional [**Banner**](#id-6.-banner) child block inside the list, and ships with three presets in the block picker: **Product list: Carousel**, **Product list: Grid**, and **Product list with banner**.

```
Product list
|-- Product card (built in)
`-- Banner (optional)
```

{% hint style="info" %}
**Note:** Product list can inherit the global [product card settings](/arctos-theme/theme-settings/product-card.md) from theme settings. Turn on the Product card's custom settings only when this list needs different product-card styling or behavior.
{% endhint %}

### 3. How to add a Product list block

{% stepper %}
{% step %}
**Open a compatible section**

In the Theme Editor (Customize), open a compatible section or container.
{% endstep %}

{% step %}
**Add a product list block**

Click **Add block**, then select **Product list**.
{% endstep %}

{% step %}
**Choose your products**

Select a **Collection** or pick specific **Products**.
{% endstep %}

{% step %}
**Set the number of products**

Specify how many products to show.
{% endstep %}

{% step %}
**Choose your display format**

Select **Grid** or **Carousel**.
{% endstep %}

{% step %}
**Configure the product card**

Adjust the built-in Product card only if this list needs different settings from the global product card settings.
{% endstep %}

{% step %}
**Preview the list**

Check how it looks on desktop and mobile.
{% endstep %}

{% step %}
**Save your changes**

Click **Save**.
{% endstep %}
{% endstepper %}

### 4. Product list settings

<details>

<summary>Product source</summary>

Use these settings to choose which products appear and how many cards the block can show.

<table><thead><tr><th width="120.17578125">Setting</th><th width="109.5859375">Options</th><th width="453.11328125">What it does</th></tr></thead><tbody><tr><td><strong>Collection</strong></td><td>Collection picker</td><td>Selects the Shopify collection used as the product source.</td></tr><tr><td><strong>Products</strong></td><td>Product list picker</td><td>Selects specific products manually. When products are selected here, they replace the selected collection.</td></tr><tr><td><strong>Number of products to show</strong></td><td>2-15</td><td>Controls the maximum number of product cards displayed in the block.</td></tr></tbody></table>

{% hint style="info" %}
**Note:** If **Products** is empty, Product list uses the selected **Collection**. If both are empty, the theme can show placeholder product cards while you build the layout.
{% endhint %}

</details>

<details>

<summary>Layout, desktop, and mobile</summary>

Product list uses the same core grid, carousel, gap, control-button, pagination, hint, and mobile-carousel patterns as [Custom list](/arctos-theme/blocks/layout/custom-list.md). Use the Custom list guide for deeper guidance on choosing between **Grid** and **Carousel**, spacing repeated cards, and deciding whether to show controls or pagination.

</details>

<details>

<summary>Style</summary>

Style controls set the color context for the complete Product list.

<table><thead><tr><th width="100.2890625">Setting</th><th width="100.3828125">Options</th><th width="481.61328125">What it does</th></tr></thead><tbody><tr><td><strong>Inherit color scheme</strong></td><td><ul><li>On</li><li>Off</li></ul></td><td><ul><li>Turning this <strong>On</strong> matches the Product list colors to the section or block it sits in.</li><li>Turning it <strong>Off</strong> lets you pick a unique color scheme for the Product list.</li></ul></td></tr><tr><td><strong>Color scheme</strong></td><td>Color scheme picker</td><td>Use the picker to select a color scheme set in <a href="/arctos-theme/theme-settings/colors.md">Theme settings > Colors</a>. <em>Only available when <strong>Inherit color scheme</strong> is off.</em></td></tr></tbody></table>

</details>

<details>

<summary>Spacing</summary>

Spacing controls add space inside or around the complete Product list.

<table><thead><tr><th width="109.83203125">Setting</th><th width="100.31640625">Options</th><th width="472.80078125">What it does</th></tr></thead><tbody><tr><td><strong>Padding</strong></td><td><ul><li>On</li><li>Off</li></ul></td><td>Adds space inside the Product list, between the block edge and the product cards. Turn it on to reveal top, bottom, left, and right padding controls from 0-200px.</td></tr><tr><td><strong>Custom on mobile</strong></td><td><ul><li>On</li><li>Off</li></ul></td><td>Reveals separate mobile padding values from 0-100px. Available when <strong>Padding</strong> is on.</td></tr><tr><td><strong>Margin</strong></td><td><ul><li>On</li><li>Off</li></ul></td><td>Adds space around the Product list to separate it from neighboring blocks. Turn it on to reveal top, bottom, left, and right margin controls from 0-200px.</td></tr><tr><td><strong>Custom on mobile</strong></td><td><ul><li>On</li><li>Off</li></ul></td><td>Reveals separate mobile margin values from 0-100px. Available when <strong>Margin</strong> is on.</td></tr></tbody></table>

</details>

### 5. Product card settings

The built-in **Product card** follows [Theme settings > Product card](/arctos-theme/theme-settings/product-card.md) unless you enable custom overrides below:

| Setting                                                    | Options                                                                                                                                                                                                                                                                        | What it does                                                                                                                                                                                                                 |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Custom product media**                                   | <ul><li>On</li><li>Off</li></ul>                                                                                                                                                                                                                                               | Overrides global product card media settings with block-specific **Ratio**, **Hover interaction**, **Transition effect** (**Fade**, **Slide**), **Direction from** (**Left**, **Right**, **Bottom**), and **Corner radius**. |
| **Custom product information** & **Custom color swatches** | <ul><li>Position (Outside, Inside), Style (Classic, Boxed), Alignment</li><li>Show vendor, Show category, Show price range label, Show product rating</li><li>Title text style, Price text style, Show color swatches, Type</li></ul>                                          | Controls product metadata, typography presets, and color swatches on cards in this list.                                                                                                                                     |
| **Custom product badges**                                  | <ul><li>Show sale badge (Type: Text, Percent, Fixed)</li><li>Show sold out badge</li><li>Custom product tags formatted as <code>badge:\<text></code></li></ul>                                                                                                                 | Configures sale, sold-out, and tag-based badges on cards in this list.                                                                                                                                                       |
| **Custom quick actions**                                   | <ul><li>Desktop / Mobile quick add button</li><li>Desktop / Mobile quick view button</li><li>Quick add button type (Icon, Text, Mix) and Quick add button width (Fit, Fill)</li><li>Quick view button type (Icon, Text, Mix) and Quick view button width (Fit, Fill)</li></ul> | Overrides quick add and quick view button visibility, type, and width (\`Fit\` or \`Fill\`).                                                                                                                                 |

### 6. Banner

A **Banner** sits inside the product list like an extra card: an image or video with its own text, buttons and other blocks on top. Use it to break up a grid with a campaign message, or to lead a carousel. The **Product list with banner** preset starts with one. You can add several.

{% hint style="info" %}
**Where to find it:** In the theme editor (**Customize**), expand the **Product list** block, click **Add block**, and choose **Banner**. Then add headings, text, buttons or other blocks inside the banner.
{% endhint %}

<details>

<summary>Size</summary>

<table><thead><tr><th width="160">Setting</th><th width="150">Options</th><th>What it does</th></tr></thead><tbody><tr><td><strong>Banner position</strong></td><td>1–16 (default 2)</td><td>The banner's place in the list, counting products and other banners. If the number is higher than the number of items, the banner appears last.</td></tr><tr><td><strong>Height</strong></td><td><ul><li>Fill [default]</li><li>Custom</li></ul></td><td><strong>Fill</strong> stretches the banner to the height of its row, never shorter than a product card's image. <strong>Custom</strong> gives the banner its own shape with <strong>Orientation</strong>.</td></tr><tr><td><strong>Orientation</strong></td><td><ul><li>Inherit [default]</li><li>Portrait</li><li>Landscape</li><li>Square</li></ul></td><td><strong>Inherit</strong> uses the product card image ratio. <strong>Portrait</strong> adds a <strong>Ratio</strong> of 4:5 or 5:7, and <strong>Landscape</strong> a <strong>Ratio</strong> of 5:4 or 4:3. <em>Available when <strong>Height</strong> is <strong>Custom</strong>.</em></td></tr><tr><td><strong>Custom on mobile</strong></td><td><ul><li>On</li><li>Off</li></ul></td><td>Set a separate mobile <strong>Height</strong>, <strong>Orientation</strong> and <strong>Ratio</strong>.</td></tr></tbody></table>

</details>

<details>

<summary>Media</summary>

<table><thead><tr><th width="160">Setting</th><th width="150">Options</th><th>What it does</th></tr></thead><tbody><tr><td><strong>Type</strong></td><td><ul><li>Image</li><li>Video</li></ul></td><td>Choose an image or a video for the banner background, then pick the <strong>File</strong>.</td></tr><tr><td><strong>Show different media on mobile</strong></td><td><ul><li>On</li><li>Off</li></ul></td><td>Use a separate image or video on mobile. When it's on, mobile shows only the mobile media, or a placeholder if it's empty.</td></tr></tbody></table>

</details>

<details>

<summary>Inner content layout, Style, Interaction and Spacing</summary>

These work like the same groups on the [Banner](/arctos-theme/blocks/media/banner.md) block:

* **Inner content layout:** **Direction** (Vertical or Horizontal), **Alignment**, **Position** and **Gap** for the blocks inside the banner, with **Custom on mobile**.
* **Style:** **Inherit color scheme** (off by default, so the banner uses its own **Color scheme**), **Filter presets**, **Overlay** and **Enable parallax effect**.
* **Interaction:** **Full banner link** makes the whole banner a link (with **Link** and **Open in new tab**). **Hover interaction**: None, Zoom in, Grayscale, Color overlay, Reveal image or Play video.
* **Spacing:** **Padding** (on by default, with top, bottom, left and right values) and **Custom on mobile** (on by default).

</details>