> 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/layout/custom-list.md).

# Custom list

Arrange reusable blocks as a responsive grid or carousel with desktop and mobile controls.

The **Custom list** block arranges repeated content blocks in a grid or carousel. Use it when you want to show a flexible set of images, banners, testimonials, icons, product callouts, or mixed promotional cards with shared spacing and carousel behavior.

### 1. What you can do

* Display inner blocks as a grid or carousel
* Set desktop rows, items per row, item alignment, vertical gaps, and horizontal gaps
* Convert a desktop grid into a carousel on mobile
* Choose linear autoplay or step-based autoplay for carousel layouts
* Show or hide carousel controls, pagination, hint previews, and infinite looping
* Add a Group inside the list when each repeated item needs its own nested layout, background, border, or spacing
* Adjust color scheme, padding, and margin around the complete Custom list

### 2. How to add a Custom list

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

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

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

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

{% step %}
**Add blocks to the list**

Add the blocks you want to repeat inside the Custom list.
{% endstep %}

{% step %}
**Choose your layout**

Select **Grid** or **Carousel** under the Custom list layout settings.
{% endstep %}

{% step %}
**Adjust the settings**

Control desktop and mobile rows, item counts, spacing, controls, and autoplay.
{% endstep %}

{% step %}
**Add nested content**

Add a **Group** inside the list when one item needs its own nested content and styling.
{% endstep %}

{% step %}
**Preview the result**

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

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

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

### 3. Custom list settings

<details>

<summary>Layout</summary>

Choose whether the list is static or browsable, then configure carousel motion when needed.

<table data-search="false"><thead><tr><th width="110.7734375">Setting</th><th width="139.703125">Options</th><th width="429.95703125">What it does</th></tr></thead><tbody><tr><td><strong>Display</strong></td><td><ul><li>Grid</li><li>Carousel</li></ul></td><td><ul><li><strong>Grid</strong> shows items in visible rows so customers can scan the content without interacting.</li><li><strong>Carousel</strong> turns the items into a browsable slider, useful when you need to show many items in less vertical space.</li></ul></td></tr><tr><td><strong>Auto play</strong></td><td><ul><li>None</li><li>Linear</li><li>Step based</li></ul></td><td><ul><li><strong>None</strong> keeps the carousel still until customers browse it.</li><li><strong>Linear</strong> creates continuous scrolling motion.</li><li><strong>Step based</strong> advances from one carousel view to the next after a set delay.</li></ul><p><em>Available when <strong>Display</strong> is <strong>Carousel</strong>.</em></p></td></tr><tr><td><strong>Direction</strong></td><td><ul><li>From left</li><li>From right</li></ul></td><td><p>Chooses the direction of continuous carousel movement.</p><p><em>Available when <strong>Auto play</strong> is <strong>Linear</strong>.</em></p></td></tr><tr><td><strong>Speed</strong></td><td><ul><li>Slow</li><li>Normal</li><li>Fast</li></ul></td><td><p>Controls how quickly the linear carousel scrolls. Use slower speeds when items contain text or details customers need to read.</p><p><em>Available when <strong>Auto play</strong> is <strong>Linear</strong>.</em></p></td></tr><tr><td><strong>Enable pause on hover</strong></td><td><ul><li>On</li><li>Off</li></ul></td><td><p>Lets desktop customers pause linear movement by hovering over the list.</p><p><em>Available when <strong>Auto play</strong> is <strong>Linear</strong>.</em></p></td></tr><tr><td><strong>Enable drag interaction</strong></td><td><ul><li>On</li><li>Off</li></ul></td><td><p>Lets customers drag or swipe the linear carousel. Keep this on when customers should be able to browse at their own pace.</p><p><em>Available when <strong>Auto play</strong> is <strong>Linear</strong>.</em></p></td></tr><tr><td><strong>Change slide every</strong></td><td>2-15s</td><td><p>Sets how long each carousel view stays visible before the next one appears.</p><p><em>Available when <strong>Auto play</strong> is <strong>Step based</strong>.</em></p></td></tr><tr><td><strong>Enable infinite loop</strong></td><td><ul><li>On</li><li>Off</li></ul></td><td><p>Sends customers from the last carousel view back to the first, creating a continuous browsing experience.</p><p><em>Available for non-linear carousel modes.</em></p></td></tr><tr><td><strong>Enable hint</strong></td><td><ul><li>On</li><li>Off</li></ul></td><td><p>Reveals part of the neighboring carousel item so customers can tell there is more content to browse.</p><p><em>Available when <strong>Display</strong> is <strong>Carousel</strong> and <strong>Auto play</strong> is not <strong>Linear</strong>.</em></p></td></tr></tbody></table>

</details>

<details>

<summary>Desktop</summary>

Control how many items appear on larger screens and how much room sits between them.

<table data-search="false"><thead><tr><th width="125.1015625">Setting</th><th width="119.9765625">Options</th><th width="437.94921875">What it does</th></tr></thead><tbody><tr><td><strong>Rows</strong></td><td>1-3</td><td><p>Sets how many rows appear inside each carousel view.</p><p><em>Available when <strong>Display</strong> is <strong>Carousel</strong>.</em></p></td></tr><tr><td><strong>Items per row</strong></td><td>1-8</td><td>Sets how many items appear across each desktop row. Fewer items create larger, more prominent cards; more items create a denser browsing area.</td></tr><tr><td><strong>Position</strong></td><td><ul><li>Top</li><li>Middle</li><li>Bottom</li></ul></td><td>Aligns items with different heights along the row. Available for carousels, or for grids when desktop <strong>Items per row</strong> is greater than 1.</td></tr><tr><td><strong>Vertical gap</strong></td><td><ul><li>Default</li><li>0–32px</li><li>Custom</li></ul></td><td>Sets the spacing between rows. Available for grids, or for carousels with more than one row.</td></tr><tr><td><strong>Horizontal gap</strong></td><td><ul><li>Default</li><li>0–32px</li><li>Custom</li></ul></td><td>Sets the spacing between items across a row. Available for carousels, or for grids when desktop <strong>Items per row</strong> is greater than 1.</td></tr><tr><td><strong>Desktop navigation buttons</strong></td><td><ul><li>None</li><li>Inside</li><li>Outside</li><li>Bottom</li></ul></td><td><ul><li><strong>None</strong> hides the previous and next buttons.</li><li><strong>Inside</strong> places controls over the carousel area.</li><li><strong>Outside</strong> keeps controls beside the carousel.</li><li><strong>Bottom</strong> places controls below the items.</li></ul><p><em>Available when <strong>Display</strong> is <strong>Carousel</strong> and <strong>Auto play</strong> is not <strong>Linear</strong>.</em></p></td></tr><tr><td><strong>Hide pagination</strong></td><td><ul><li>On</li><li>Off</li></ul></td><td><p>Removes the desktop progress indicator when controls or dragging are enough.</p><p><em>Available when <strong>Display</strong> is <strong>Carousel</strong> and <strong>Auto play</strong> is not <strong>Linear</strong>.</em></p></td></tr><tr><td><strong>Show pagination background</strong></td><td><ul><li>On</li><li>Off</li></ul></td><td><p>Adds a background behind pagination so it stays visible against item colors or media.</p><p><em>Available when pagination is shown.</em></p></td></tr></tbody></table>

</details>

<details>

<summary>Mobile</summary>

Mobile settings follow the same pattern as desktop: you can enable a mobile carousel (if using a grid on desktop), and adjust the rows, items per row, position, vertical/horizontal gaps, control buttons, and pagination for smaller screens.

</details>

<details>

<summary>Style</summary>

<table><thead><tr><th width="100.44921875">Setting</th><th width="100.3671875">Options</th><th width="480.53125">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 Custom list colors to the section or block it sits in.</li><li>Turning it <strong>Off</strong> lets you pick a unique color scheme to make the Custom list stand out.</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#general-colors">Theme settings > Colors</a>.</td></tr></tbody></table>

</details>

<details>

<summary>Spacing</summary>

<table><thead><tr><th width="113.93359375">Setting</th><th width="192.8046875">Options</th><th width="375.23828125">When to use</th></tr></thead><tbody><tr><td><strong>Padding</strong></td><td>Custom value per side</td><td>Sets the spacing between the block and its surrounding edge.</td></tr><tr><td><strong>Margin</strong></td><td>Custom value per side</td><td>Sets the spacing around the block to separate it from neighboring blocks.</td></tr><tr><td><strong>Custom on mobile</strong></td><td><ul><li>On</li><li>Off</li></ul></td><td>Set separate padding and margin values for mobile.</td></tr></tbody></table>

</details>