The rich vertical list is a two-column pattern that pairs structured content (title, descriptions, lists, logos, CTAs) with a single media element (image or video) on the opposite column. By default, content is on the left and media is on the right; this can be swapped with is_flipped.
Internally, the content column uses content blocks from the Basic section pattern, with the per-type configuration for supported items following the basic section format. The distinguishing feature is the dedicated media column with per-breakpoint aspect-ratio configuration and an optional auto-height mode.
The rich vertical list pattern is composed of the following elements:
| Element | Description |
|---|---|
| Title (required) | <h2> heading, optionally wrapped in a link |
| Items | Array of supported content blocks: text (description), list, code block, logo block, CTA block |
| Media (required) | A single image or video, configured via the media parameter |
The horizontal ordering of the rich list columns can be reversed, placing the media on the left and the content on the right.
The only mandatory elements are the title and the media. Items are optional — passing items=[] (or omitting it entirely) renders just the title and media columns.
The media column is configured via the media parameter. Its key fields are:
type — "image" (default) or "video".ratio.large — aspect ratio at the large breakpoint. Supported: "16-9", "3-2" (default), "1-1", "2-3", "auto-height".ratio.medium_small — aspect ratio at medium and small breakpoints. Supported: "16-9", "3-2" (default), "1-1". ("auto-height" is not supported here — see Auto-height below.)fit — "cover" (default) or "contain". Applies to images only.attrs — passthrough HTML attributes for the underlying <img> or <iframe> (e.g., src, alt, allowfullscreen).Set media.ratio.large and media.ratio.medium_small to control how the media wrapper sizes itself at each breakpoint. The image inside is rendered with object-fit: cover (default) or contain.
Setting media.ratio.large to "auto-height" makes the media column stretch to match the content column's rendered height on large screens, clamped between a 16:9 minimum and a 2:3 maximum of the column's width. Useful when the content varies in length and a fixed aspect ratio leaves awkward whitespace.
auto-height is only valid at the large breakpoint. On medium and small screens the columns stack, so media.ratio.medium_small falls back to a fixed ratio.
Auto-height should be used sparingly to maintain visual consistency across the page:
Setting media.type to "video" renders the media as an embedded iframe inside .u-embedded-media. The aspect ratio is fixed at 16:9 by the underlying utility — media.ratio and media.fit are ignored when type is "video".
The rich vertical list supports customizable padding using the section pattern. By default, the pattern is wrapped in a regular section.
Supported variants:
"default" — p-section for standard spacing (default)"deep" — p-section--deep for maximum spacing"shallow" — p-section--shallow for reduced spacingPlease refer to the section documentation for more guidance on padding selection.
By default, the rich vertical list has a default horizontal rule at the top.
You can customize this using the top_rule_variant parameter.
Supported variants:
"default" — Standard horizontal rule"muted" — Lighter/muted horizontal ruleThe items array reuses the basic section content blocks model, but the rich vertical list pattern only supports a curated subset of types. Entries with any other type are silently dropped.
Supported types and their per-type configurations:
type: 'description'. See Description block.type: 'list'. See List block.type: 'code-block'. See Code block.type: 'logo-block'. See Logo block.type: 'cta-block'. See CTA block.The vf_rich_vertical_list Jinja macro can be used to generate a rich vertical list pattern. The API for the macro is shown below.
| Name | Required? | Type | Default | Description |
|---|---|---|---|---|
title
|
Yes |
Object
|
N/A
|
Title configuration object with text and optional link_attrs.
|
title.text
|
Yes |
string
|
N/A
|
The main title text (rendered as h2). |
title.link_attrs
|
No |
Object
|
N/A
|
Attributes of an anchor element, as a dictionary. See attribute forwarding docs for more info. |
items
|
No |
Array<Object>
|
[]
|
Array of content blocks rendered in order in the content column. Supported types: description, list, code-block, logo-block, cta-block. See Items for per-type configurations. Entries with any other type are silently dropped.
|
media
|
Yes |
Object
|
N/A
|
Media column configuration. See Media for details. |
media.type
|
No |
One of:'image','video'
|
'image'
|
The media type rendered in the opposite column. |
media.ratio.large
|
No |
One of:'16-9','3-2','1-1','2-3','auto-height'
|
'3-2'
|
Aspect ratio of the media wrapper at the large breakpoint. Ignored for type: 'video'.
|
media.ratio.medium_small
|
No |
One of:'16-9','3-2','1-1'
|
'3-2'
|
Aspect ratio at the medium and small breakpoints. Ignored for type: 'video'.
|
media.fit
|
No |
One of:'cover','contain'
|
'cover'
|
Object-fit applied to the image. Ignored for type: 'video'.
|
media.attrs
|
No |
Object
|
{}
|
Passthrough HTML attributes for the underlying <img> or <iframe>. Typically includes src and alt for images, or src and allowfullscreen for videos.
|
is_flipped
|
No |
boolean
|
false
|
Swap the content and media columns so the media is on the left. |
padding
|
No |
One of:'deep','shallow','default'
|
'default'
|
Padding variant for the entire section. See section pattern for details. |
top_rule_variant
|
No |
One of:'default','muted'
|
'default'
|
Variant of horizontal rule to display at the top of the section. |
attrs
|
No |
Object
|
{}
|
Attributes to apply to the section element, as a dictionary. See attribute forwarding docs for more info. |
To import the Rich Vertical List Jinja macro, copy the following import statement into your Jinja template.
{% from "_macros/vf_rich-vertical-list.jinja" import vf_rich_vertical_list %}
View the building with Jinja macros guide for macro installation instructions.
Since Patterns leverage many other parts of Vanilla in their composition and content, we recommend importing the entirety of Vanilla for full support.