A component that generates a table of contents to be embedded within the page. It accepts a dictionary of heading names and IDs when in 'manual' mode but can also be used in 'full-page' mode to auto-generate them (this requires the associated JS).
Clicking the links will take you to that heading in the page. The navigation also highlights the current position you are in the page.
The in-page navigation component is composed of the following elements:
| Element | Description |
|---|---|
| title | Optional title above the navigation |
| navigation_items | A dictionary of the heading names, IDs |
| scope | Whether the navigation will be manual built or generated by JS |
| primary_heading | The level of the primary headings ('h2' or 'h3') |
| secondary_heading | The level of the secondary headings ('h3' or 'h4') |
| excludes | An optional list of headings to ignore |
The navigation is always expected to be used within the grid (whether in "manual" or "full-page" mode). It should have a grid column as a direct parent and preferably be in 2 columns on large screens, and 4 columns on medium and small screens.
There is an option to add a heading on top of the in-page navigation component, which can be helpful in cases where the in-page navigation targets a specific section, not the entire page.
This is an example of "full-page" mode with mock content. The navigation has been auto-generated:
Full-page mode example with mock content
This is an example of "manual" mode, where a dictionary of headings was passed to the Jinja macro. In this instance it is found half way down the page:
Manual mode example with mock content
The vf_in_page_navigation Jinja macro can be used to generate an in-page navigation. The API for the macro is shown
below.
| Name | Required? | Type | Default | Description |
|---|---|---|---|---|
title
|
No |
String
|
N/A
|
The title of the in-page navigation |
navigation_items
|
No |
Object
|
N/A
|
The navigation represented as an object. The hierarchy and order of the navigation should be reflected in the object to a maximum of 2 levels deep. |
navigation_items{}.text
|
Yes (if passing `navigation_items`) |
String
|
N/A
|
The title as it will appear in the navigation |
navigation_items{}.id
|
Yes (if passing `navigation_items`) |
String
|
N/A
|
The ID of the target heading |
scope
|
No |
String
|
"full-page"
|
"full-page" - Automatically generates the in-page navigation and attaches heading IDs. Max 1 navigation per page. Requires associated JS. "manual" - Requires passing `navigation_items` dictionary. No limit on number of navigations per page. |
primary_heading
|
No |
String
|
"h2"
|
The top level heading that is searched for when auto-generating the navigation. |
secondary_heading
|
No |
String
|
N/A
|
The second level heading that is searched for when auto-generating the navigation. Should follow `primary_heading` numerically for semantic correctness i.e. "h2" -> "h3". |
excludes
|
No |
Array<String>
|
[]
|
Array of headings to exclude from the navigation, supports two formats: CSS selector (e.g. "#some-id", ".some-class") - Matches based on css selectors Text match (e.g. "text:Newsletter") - Matches based on text content of headings. Must be prepended with `text:`. |
To import the Basic Section Jinja macro, copy the following import statement into your Jinja template.
{% from "_macros/vf_in-page-navigation.jinja" import vf_in_page_navigation %}
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.