> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olonjs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tags List section — display a collection of topic cards

> The Tags List section renders a card grid from a tags collection reference. Use it to let visitors browse topics on home or tags index pages.

The `tags-list` section renders a grid of topic cards sourced from your tags collection. Each card links to the corresponding tag page, where the inverse relation between tags and posts is resolved at render time.

Use `tags-list` on the home page to give visitors a topic-first entry point, on the tags index page as the primary content, and on the posts archive page as a secondary navigation aid.

***

## Data fields

<ParamField body="label" type="string">
  An eyebrow label rendered above the section title — for example `"Topics"` or `"Another way in"`. Optional.
</ParamField>

<ParamField body="title" type="string" required>
  The section heading — for example `"Browse by topic"` or `"All topics"`.
</ParamField>

<ParamField body="description" type="string">
  A short supporting sentence below the title. Optional. Use it to explain the relationship between tags and posts — for example `"Six tags, one collection. Each card links to a tag page that computes its own post list from the relation."`.
</ParamField>

<ParamField body="items" type="CollectionRef" required>
  A reference to the tags collection file. Provide a `$ref` key pointing to the relative path of `tags.json`. OlonJS resolves the reference at build time and renders one card per tag entry.

  ```json theme={null}
  "items": {
    "$ref": "../collections/tags/tags.json"
  }
  ```

  The `$ref` path is relative to the page JSON file that contains the section. See the [Collections](/concepts/collections) guide for details.
</ParamField>

<Note>
  Like `posts-list`, the `items` field uses the `ui:collection-ref` hint. In OlonJS Studio, it renders as a collection picker — you select the tags collection from a dropdown rather than typing the path manually.
</Note>

***

## Settings fields

<ParamField body="paddingTop" type="&#x22;none&#x22; | &#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22; | &#x22;xl&#x22;">
  Vertical padding applied above the section.
</ParamField>

<ParamField body="paddingBottom" type="&#x22;none&#x22; | &#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22; | &#x22;xl&#x22;">
  Vertical padding applied below the section.
</ParamField>

***

## JSON example

The following example is taken from `home.json`:

```json theme={null}
{
  "id": "home-tags",
  "type": "tags-list",
  "data": {
    "label": "Topics",
    "title": "Browse by topic",
    "description": "Six tags, one collection. Each card links to a tag page that computes its own post list from the relation.",
    "items": {
      "$ref": "../collections/tags/tags.json"
    }
  },
  "settings": {}
}
```

<Tip>
  You can omit `description` when the `title` is already self-explanatory — the tags index page at `tags.json` uses only `"All topics"` as a title and no description.
</Tip>

***

## Used on pages

| Page | Role |
| - | - |
| Home (`home.json`) | Secondary navigation — gives visitors a topic-first path into the content |
| Tags index (`tags.json`) | Primary content — the full tags collection as the page's main section |
| Posts archive (`posts.json`) | Supporting navigation — offers a topic-browsing alternative to the timeline |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.