> 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/collections/collection-list.md).
# Collection list
**Collection list** shows a set of your categories as a row of image cards, each one a door into a collection page. It is the most direct way to answer a new visitor's first question, which is what kind of things this store sells, and it saves shoppers from hunting through the menu. Shoppers normally meet it high on the homepage or on a landing page, above the first row of individual products.
You choose which collections appear and in what order, so the section can promote a seasonal edit rather than simply listing everything in the catalogue.
### Where to find it
{% hint style="success" %}
**Steps:**
1. Go to **Online Store > Themes > Customize**.
2. Open the template where the categories should appear, usually the homepage.
3. Click **Add section** and choose **Collection list** from the **Collections** group.
4. Add one block per category and select the collection in each block.
5. Set the image ratio and how many cards fit per row, then check the mobile preview.
{% endhint %}
*Result:* the collections appear as cards in the order of the blocks, each linking to its collection page.
### Section settings
#### General settings
| Setting | Description |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Section width** |
How far the row of cards spreads across the screen.
Stretch width: the cards run close to both screen edges whatever the screen size.
Fixed width: the cards line up with the page width set in Theme settings > Layout, which keeps them level with the sections above.
Full width: the section fills the whole browser window and resizes with it.
|
| **Color scheme** | The background and text colours of the section. Schemes are defined in **Theme settings > Colors**, so a different scheme here marks the categories out from the product rows around them. |
#### Section header
| Setting | Description |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Heading** | The title shoppers read first, the line that explains what these categories have in common, for example `Shop by category`. |
| **Description** | A sentence under the title, useful when the grouping needs justifying, such as a seasonal or gift edit. |
| **Heading size** |
How large the title is rendered.
Heading 1: the biggest, when the categories are the main content of the page.
Heading 2: a middle size that suits most homepages.
Heading 3: the smallest, when the row supports the content around it.
|
| **Alignment** |
Where the title and its supporting line sit above the cards.
Left: lines up with the first card and reads naturally.
Center: balanced over a full row, the common choice.
Right: rarely needed, use it to mirror a neighbouring section.
|
| **Show view all button** | Adds a button next to the heading that takes shoppers to a fuller list rather than the few categories shown here. Turn it on when the section is a sample of a much longer catalogue. |
| **Button label** | The words on that button. Something specific such as `See all categories` sets a clearer expectation than a generic label. |
| **Button link** | Where that button leads, usually a page listing every collection in the store. |
#### Collection settings
| Setting | Description |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Image ratio** |
The shape every card image is cropped to, so categories with photos of different sizes still line up in a tidy row.
Adapt to image: keeps each picture as uploaded, nothing is cut off but the cards end up different heights.
Square (1:1): the most forgiving when pictures come from different sources.
Portrait (3:4): a tall crop that gives each category more presence.
Landscape (4:3): a wide crop that keeps the row compact.
|
| **Content position** |
Where the category name sits in relation to its picture.
Overlay image: the name sits on the picture, which looks bolder but needs images with calm space in them.
Below image: the name sits under the picture, which stays readable whatever the photography looks like.
|
| **Content alignment** |
Where the category name starts within its card.
Left: reads naturally and lines the names up down the row.
Center: gives each card a more symmetrical, editorial look.
|
| **Show product count** | Adds the number of items in each category under its name. It reassures shoppers a category is worth entering, and exposes the ones that are nearly empty. |
| **Items per row on desktop** | How many cards sit side by side on a wide screen. More per row means smaller pictures and category names that wrap sooner. |
| **Column gap** | The space between cards. Tight gaps make the categories read as one block, wider gaps give each one its own presence. |
#### Overlay image settings
| Setting | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Text color** |
The colour of the category name where it sits on top of the picture. Choose it against your darkest and lightest images, not just one of them.
Note: only applies when Content position is set to Overlay image.
|
#### Carousel settings
| Setting | Description |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Enable carousel** | Turns the grid into a swipeable row instead of wrapping cards onto more lines. Use it when you have more categories than fit comfortably on one row. |
| **Show navigation** | Shows the previous and next arrows. Keep them on for desktop, where shoppers have no swipe gesture. |
| **Navigation position** | Where those arrows sit: **Default** keeps them with the row of cards, **Section header** moves them up beside the title, which keeps them in one predictable place. |
| **Show pagination** | Shows the dots under the row, which tell shoppers how many categories are in the carousel and where they are in it. |
| **Reveal next slide** | Leaves part of the following card peeking in at the edge, a visual hint that there is more to swipe to. |
| **Items per row on mobile** | How many cards fit across a phone screen. One gives large, tappable cards; two lets shoppers compare categories at a glance. |
#### Section padding
| Setting | Description |
| ---------- | ---------------------------------------------------------------------------------------------------- |
| **Top** | Space added above the section. Increase it when the heading sits too close to the section before it. |
| **Bottom** | Space added below the section. Increase it when the next section crowds the cards. |
#### Section divider
| Setting | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Show divider** | Draws a thin horizontal line at the section edge, useful when this row and its neighbour share a background colour and run into each other. |
### Block settings
Add one block per category. The order of the blocks is the order shoppers see.
| Setting | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Collection** | Which category this card opens. Shoppers who click it land on that collection page, so avoid pointing at collections you have not stocked yet. |
| **Image** | The picture on this card. Setting it here overrides the image the collection carries in your admin, which is how you keep the row visually consistent. |
| **Title** | The wording on the card. Use it when the collection's own name is too long or too internal to show shoppers, for example `SS25-outerwear`. |
### What changes on the storefront
* Shoppers see a row of category cards, and clicking one opens that collection page.
* A block with no **Image** falls back to the collection's own image from the admin, so an unstyled card usually means the collection has no picture there either.
* With **Show product count** on, an empty or nearly empty category advertises the fact, so hide the count or restock before publishing.
### Related pages
* [Collections](/velare/customize-your-pages/collections.md): the group this section belongs to
* [Explore collections](/velare/customize-your-pages/collections/explore-collections.md): the same card layout with a shorter set of controls
* [Collection page](/velare/customize-your-pages/collection-page.md): where every card leads
* [Colors](/velare/set-up-your-store/colors.md) and [Layout](/velare/set-up-your-store/layout.md): where the schemes and page width come from
---
# 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/collections/collection-list.md?ask=&goal=
```
`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.