Posts List section — render a grid of collection posts

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

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.

string

required

The section heading — for example "Latest from the desk" or "The archive".

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

"bento" | "timeline"

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.

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.

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.

"items": {
  "$ref": "../collections/posts/posts.json"
}

The $ref path is relative to the page JSON file that contains the section. See the Collections guide for full details.

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.

Settings fields

"none" | "sm" | "md" | "lg" | "xl"

Vertical padding applied above the section.

"none" | "sm" | "md" | "lg" | "xl"

Vertical padding applied below the section.

JSON examples

Bento variant (home page featured posts)

{
  "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)

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

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.

Used on pages

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

Section Components

APIs & Routes

Posts List section — render a grid of collection posts

Data fields

Settings fields

JSON examples

Bento variant (home page featured posts)

Timeline variant (posts archive page)

Used on pages

​Data fields

​Settings fields

​JSON examples

​Bento variant (home page featured posts)

​Timeline variant (posts archive page)

​Used on pages

Data fields

Settings fields

JSON examples

Bento variant (home page featured posts)

Timeline variant (posts archive page)

Used on pages