> ## 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.

# Posts List section — render a grid of collection posts

> The Posts List section renders a grid or timeline of posts from a collection. Supports bento and timeline layout variants with an optional item limit.

The `posts-list` section renders a set of post cards sourced from your posts collection. You choose between two layout variants — `bento` for a masonry-style featured grid, or `timeline` for a chronological list — and you can cap the number of displayed items with an optional `limit` field.

Use `posts-list` wherever you want to surface posts on a page: as a featured preview on the home page (bento, limited to 4), as a full archive on the posts index (timeline, no limit), or as a secondary "start reading" prompt anywhere on the site.

***

## Data fields

<ParamField body="label" type="string">
  An eyebrow label rendered above the section title — for example `"Fresh ink"`. Optional. Use it to give the section a campaign or editorial name without changing the title.
</ParamField>

<ParamField body="title" type="string" required>
  The section heading — for example `"Latest from the desk"` or `"The archive"`.
</ParamField>

<ParamField body="description" type="string">
  A short supporting sentence below the title. Optional. Use it to explain the curation logic — for example `"The four most recent essays, pulled live from the posts collection and sorted by date."`.
</ParamField>

<ParamField body="variant" type="&#x22;bento&#x22; | &#x22;timeline&#x22;">
  Controls the layout of the post cards. Optional — when omitted the theme default applies.

  * **`bento`** — renders a masonry-style grid. Best for highlighted or curated subsets of posts (use with `limit`).
  * **`timeline`** — renders a vertical chronological list. Best for archive pages where you want to show all posts in order.
</ParamField>

<ParamField body="limit" type="number">
  Caps the number of posts rendered from the collection. Optional — when omitted, all items in the referenced collection are rendered. Combine with `variant: "bento"` and a value of `3` or `4` for a featured-posts panel.
</ParamField>

<ParamField body="items" type="CollectionRef" required>
  A reference to the posts collection file. You do not inline post data here — instead you provide a `$ref` key pointing to the relative path of `posts.json`. OlonJS resolves the reference at build time and injects the full collection.

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

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

<Note>
  The `items` field uses the `ui:collection-ref` UI hint, which means the OlonJS Studio renders it as a collection picker rather than a freeform input. You should never need to type the `$ref` path by hand in the Studio.
</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 examples

### Bento variant (home page featured posts)

```json theme={null}
{
  "id": "home-featured-posts",
  "type": "posts-list",
  "data": {
    "label": "Fresh ink",
    "title": "Latest from the desk",
    "description": "The four most recent essays, pulled live from the posts collection and sorted by date.",
    "variant": "bento",
    "limit": 4,
    "items": {
      "$ref": "../collections/posts/posts.json"
    }
  },
  "settings": {
    "paddingTop": "xl"
  }
}
```

### Timeline variant (posts archive page)

```json theme={null}
{
  "id": "posts-archive",
  "type": "posts-list",
  "data": {
    "title": "The archive",
    "variant": "timeline",
    "items": {
      "$ref": "../collections/posts/posts.json"
    }
  },
  "settings": {}
}
```

<Tip>
  On the archive page, omitting `limit` renders every post in the collection. Pair this with `variant: "timeline"` so the chronological ordering is visually obvious to readers.
</Tip>

***

## Used on pages

| Page | Variant | Limit |
| - | - | - |
| Home (`home.json`) | `bento` | `4` |
| Posts archive (`posts.json`) | `timeline` | none |
| Tags index (`tags.json`) | `bento` | `3` |


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