The tiered list pattern is used to easily implement a list of paired titles and descriptions underneath a top-level title and description. Optional CTA blocks can be placed at various points in the content as well. Depending on the size and composition of your content, you can choose from a variety of tiered list layouts:
The tiered list pattern is composed of the following elements:
| Element | Description |
|---|---|
| Title | h2 title text |
| Description | p description text with optional CTA block |
| Media (optional) | Image or video to show near description |
| List item title | Title text/content |
| List item description | Description text/content with optional CTA block |
| Call to action block | CTA block beneath the list |
This variant contains a top-level description which is presented side-by-side with its title on desktop screen sizes.
This variant does not contain a top-level description and its child list is presented with its titles side-by-side with its descriptions on tablet screen sizes.
This variant contains a top-level description and its child list is presented with its titles side-by-side with its descriptions on tablet screen sizes.
This variant contains a top-level description. Its title and description are presented side-by-side on desktop screen sizes, and its child list is presented side-by-side on tablet screen sizes.
This variant does not contain a top-level description, and both its title and child list are presented full-width on desktop and tablet screen sizes respectively.
This variant contains a top-level description, and its title, description, and child list are presented full-width on desktop and tablet screen sizes respectively.
In addition to the CTA block placed below the list, you may also add CTA blocks below the top-level description text, as well as below each list item's description text.
By default the pattern renders a standard horizontal rule at its top. Use the
top_rule_variant parameter to render a muted or highlighted rule, or
none to remove it.
You can embed an image or a video near the description.
You can embed a default width or full width image near the description. The image may be positioned before or after the description, depending on the variant you choose. The aspect ratio of the image depends on the variant you choose, and it will be wrapped in an image container to ensure it maintains the correct aspect ratio.
"img_attrs": {
"src": "image-url",
"alt": "alt-text",
"width": "image width",
"height": "image height",
"class": "additional image classes"
}
img_attrs: Dictionary of image attributes (src, alt, class, etc.). The p-image-container__image class is automatically applied. See attribute forwarding docs for more info.
This variant features a default width image positioned before description.
When using the default width image, the image will use half of the page width on large screens. We recommend following these guidelines when using the default width image:
3-2 aspect ratio. You can also set it to 16-9 by using media_aspect_ratio attribute.The following example demonstrates a good usage of the default width image variant:
This variant features a full width image positioned before the title and description.
When using the full width image, the image will use the full width of the page on all screens. We recommend following these guidelines when using the full width image:
cinematic aspect ratio will be automatically applied.The following example demonstrates a good usage of the full width image variant:
By default, the media is displayed after the CTA, but you can choose where it should be displayed relative to the description and CTA.
To do this, set the media_placement parameter in the Jinja macro to before_description, after_description, or after_cta.
You may also use this variant to embed a video. Videos are positioned exactly the same as images, but they always have a 16:9 aspect ratio.
When embedding a video with the Jinja macro, follow the following guidelines:
video_attrs param instead of the img_attrs param.u-embedded-media__element class, which is provided by the embedded media utility."video_attrs": {
"src": "video url",
"title": "title of the video iframe",
"allowfullscreen": "boolean - whether to allow full screen",
"class": "additional classes"
}
To embed a YouTube video with the lite-youtube custom element instead of a standard iframe,
pass video_id (and ideally video_title) in video_attrs instead of src:
"video_attrs": {
"video_id": "id of the YouTube video",
"video_title": "title of the video, used for accessibility",
"class": "additional classes"
}
Any other keys are forwarded as attributes onto the lite-youtube element. posterquality defaults to maxresdefault.
The lite-youtube script is not bundled with Vanilla, so it must be loaded on the page for the video to be playable:
<script type="module" src="https://cdn.jsdelivr.net/npm/@justinribeiro/lite-youtube@1.9.0/lite-youtube.min.js"></script>
The vf_tiered_list Jinja macro can be used to generate a tiered list pattern. The API for the macro is shown below.
| Name | Required? | Type | Default | Description |
|---|---|---|---|---|
is_description_full_width_on_desktop
|
Yes |
boolean
|
true
|
Whether the description element should be full-width on desktop |
is_list_full_width_on_tablet
|
Yes |
boolean
|
true
|
Whether the list element should be full-width on tablet |
padding
|
No |
One of:'deep','shallow','default'
|
'default'
|
Padding variant for the section |
top_rule_variant
|
No |
One of:'default','muted','highlighted','none'
|
'default'
|
Variant of the horizontal rule rendered at the top of the pattern |
img_attrs
|
No | object |
{} |
Attributes of the image to display near the description. Must have the class p-image-container__image.If the video slot is used, this slot will be ignored.
|
video_attrs
|
No | object |
{} |
Video to display near the description. Pass src to render an iframe embed.Pass video_id (and ideally video_title) instead to render a lite-youtube embed. |
is_media_full_width
|
No |
boolean
|
false
|
Whether the media should be full-width and displayed in its own row. If the media is a full-width image, a cinematic (2.4:1 aspect ratio) image container will wrap your image. If the media is a default-width image, a 16:9 image container will wrap your image. If you use the video slot, this parameter will affect the positioning of the video, but will not change its aspect ratio. Videos are always 16:9.
|
media_placement
|
No |
One of 'before_description', 'after_description', or 'after_cta'
|
'after_cta'
|
Whether the media should be full-width and displayed in its own row. If the media is a full-width image, a cinematic (2.4:1 aspect ratio) image container will wrap your image. If the media is a default-width image, a 16:9 image container will wrap your image. If you use the video slot, this parameter will affect the positioning of the video, but will not change its aspect ratio. Videos are always 16:9.
`after_description` and `after_cta` will have same effect for full-width media, i.e., media row will be rendered after description + cta combined.
|
media_aspect_ratio
|
No |
One of '3-2' or '16-9'
|
'3-2'
|
Aspect ratio to apply to media. Only applies to images, and is set to `cinematic` when `is_media_full_width` is true. Videos have `16-9` ratio always. |
hide_media_on_small_medium_breakpoints
|
No |
boolean
|
'false'
|
Whether to hide media on medium and small screens |
is_media_highlighted
|
No |
boolean
|
'false'
|
Whether to apply the "is-highlighted" class to the media container. Only applies to images |
| Name | Required? | Description |
|---|---|---|
title
|
Yes | Title sentence displayed at the top of the pattern |
description
|
No | Description paragraph displayed below the title |
list_item_title_[1-25]
|
Yes, at least 1 | Title element of each child list item; max of 25 |
list_item_description_[1-25]
|
Yes, at least 1 | Description element of each child list item; max of 25 |
cta
|
No | Contents of a CTA block at the bottom of the pattern |
To import the Tiered List Jinja macro, copy the following import statement into your Jinja template:
{% from "_macros/vf_tiered-list.jinja" import vf_tiered_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.