Documentation
An in-page navigation module for HubSpot CMS. It shows the sections of a long page as a bar that sticks under your
site header, or as a rail down the side. While someone reads, the link of the section they are in is marked. A click
scrolls to that section and stops with its heading just below your header and the bar.
Everything runs in the visitor's browser: no HubDB table, no outside service, no extra library.
In the page editor's module list it is called Section Nav Pro.
Contents
Install
- Buy the module on the HubSpot Marketplace. It appears in your portal under Content → Design Manager, in the
marketplace folder, and in the page editor's module list as Section Nav Pro.
- It works on website pages, landing pages, blog posts and blog listing pages, in any theme.
Set it up in three steps
1. Add the module. Open the page in the page editor and drag Section Nav Pro into a drag-and-drop area. For a
bar, put it in a full-width section of its own, right above the content it points to (under the page's hero, for
example). For a rail, put it in a narrow column (about a quarter of the row) beside the column that holds your sections.
2. Point it at your sections. In Links → Build the links from pick one:
- Automatic (the default) makes a link for every
h2 on the page, with the heading's text as the label. Nothing
else to do if your sections start with H2 headings. To read only part of the page, put a selector in
Look only inside.
- Your own list: add a link per section, type the words, and put the section's anchor in Section anchor.
See How anchors work in HubSpot for where anchors come from.
3. Pick a layout. In Layout, choose Bar or Rail, the bar's alignment and style (underline, pill
or segmented), and what phones get: a row they can swipe or a dropdown. Publish and scroll the live page; the page
editor never makes it stick (see In the page editor).
How anchors work in HubSpot
An anchor is the id of an element on the page. A link to #pricing goes to the element with id="pricing". The
module's links use the same anchors.
Automatic mode makes its own. Each heading it picks up that has no id gets one from its text: "Pricing and plans"
becomes pricing-and-plans. If two headings have the same text, the second gets -2. Those anchors work for other
links too, so a button elsewhere can link to #pricing-and-plans.
For your own list, there are three ways to get an anchor:
- A rich text anchor. In a rich text module at the top of the section, put the cursor before the heading and
choose Insert → Anchor in the toolbar. Give it a name, such as
pricing, and type that name in
Section anchor. Anchor names are case-sensitive: Pricing and pricing are different anchors.
- An anchor or ID setting on a module or section. Many theme modules have their own anchor or ID field, and some
editors let you set an ID on a section. Whatever you type there is the anchor.
- A class. If the section already has a class, type it with its dot, such as
.pricing-row. The first element
with that class is used.
A link whose anchor is not on the page is hidden from visitors, so a typo never leaves a link that does nothing. In the
page editor that link stays visible, greyed out, with a note above the module naming the missing anchors.
Arriving with an anchor. A visitor who opens /page#pricing from another page lands with the Pricing section below
the header and the bar, not under them.
How it behaves
The bar stays where you placed it until it reaches the bottom of your site header, then stays there while the page
scrolls. It finds the header itself: anything fixed or sticky at the top of the screen, up to half the screen tall. It
looks again as the page scrolls and when the window changes size, so a header that shrinks, hides or grows on scroll is
followed. If nothing is fixed at the top, the bar sticks to the very top of the screen.
When the bar sticks, the space it took on the page is kept, so the content under it does not jump.
Jumping to a section
A click scrolls to the section and stops with its top just below the header and the bar, plus
Space above a section after a jump. Once the scroll ends, the module measures again and corrects the last pixel, for headers
that changed height on the way. The clicked link stays marked until the reader scrolls on.
Visitors whose device asks for reduced motion jump without scrolling, and Smooth scrolling off does the same
for everyone.
Which link is marked
A section becomes current when its top passes a line just below the bar (A section becomes current when it is this far from the bar sets how far
below). At the very bottom of the page the last link is marked, even when the last section is too short to reach the line.
Rail
A rail sits in its column and slides down with the reader, staying inside its row, so it never runs into the section
below. Below Phone layout below it turns into a bar above the content.
Phones
Below Phone layout below the bar switches to the phone layout you picked in On phones:
- A row you can swipe. Every link stays in one row; the current one scrolls into the middle of the row as the reader
goes. The page itself never moves sideways.
- A dropdown. One button with the current section's name. Tap it to open the list, tap a section to go there. It
closes on a tap outside or with Escape.
Several on one page
Each instance works on its own. When the next bar on the page arrives under the header, it pushes the one above it out
of the way, so two bars never stack.
In the page editor
In the page editor the module shows in place, as visitors see it before scrolling. It never sticks or hides there, and
clicking a link does nothing, so you can select and edit the module. A note above it (only in the editor) says when
links are hidden because their anchor is not on the page, or when automatic mode found no headings. In automatic mode the
editor shows the links once the page's headings have loaded; preview the page to check them.
Keyboard and screen readers
The links sit in a nav landmark named by Name for screen readers. The current link has aria-current="location".
Following a link with the keyboard moves focus to the section, so the next Tab continues from there. The dropdown button
says whether it is open (aria-expanded), and Escape closes it.
Field reference — Content tab
Links
Where the links come from.
| Field |
Default |
What it does |
| Build the links from |
The headings on this page (automatic) |
Automatic reads the headings on the page each time it loads and makes one link per heading, with the heading text as the label. A list you write gives you the words, the order and an icon per link. |
| Headings to use |
“h2” |
Which elements count as headings, as a CSS selector. h2 takes every main heading; h2, h3 adds sub-headings; [data-nav] takes only elements you mark. A heading with no id gets one made from its text (for example pricing-and-plans). |
| Look only inside |
empty |
Optional CSS selector for the part of the page to read, such as main, .body-container or #article. Empty reads the whole page and skips headings inside headers, footers, menus, dialogs and hidden areas. |
| Skip headings matching |
empty |
Optional CSS selector of headings to leave out. A heading with the attribute data-section-nav-pro-skip (or inside an element that has it) is always left out, and data-section-nav-pro-label="Short name" on a heading sets its link text. |
| Most links |
10 |
Headings after this number are left out. |
Links
Your links, in order. Shown when Build the links from is set to your own list.
Repeater: 1 to 20 links. Each link has:
| Field |
Default |
What it does |
| Link text |
“Section” |
The words on the link. |
| Section anchor |
empty |
The anchor of the section to jump to, without # (a leading # is removed for you). It can also be a class or attribute selector that starts with . or [, such as .pricing-row. A link whose section is not on the page is hidden from visitors and greyed out in the editor. |
| Icon (optional) |
none |
An icon before the words. |
Layout
Bar or rail, and how each looks on phones.
| Field |
Default |
What it does |
| Layout |
Bar: a strip across the page |
A bar is a strip across the page that sticks under your site header. A rail is a vertical list for a narrow column beside your content; it follows the reader down its row. Below Phone layout below a rail becomes a bar. |
| Links in the bar |
Centred |
Where the links sit in the bar. Full width shares the width between the links. |
| Bar style |
Underline |
How the current link is marked: a line under it, a filled pill behind it, or a raised segment in a groove that holds every link. |
| Number the links |
Off |
Puts 01, 02, 03 before each link in the rail. |
| Progress line beside the links |
On |
A thin line down the side of the rail that fills to the current link. |
| Title above the rail |
“On this page” |
A small heading above the rail. Empty shows no title. |
| On phones |
A row you can swipe (the current link scrolls into view) |
A row you can swipe keeps every link and scrolls the current one into view. The dropdown shows one button with the current section’s name; a tap opens the full list. |
| Phone layout below |
768 px |
Screen width, in pixels, below which the phone layout is used. |
An optional button at the end of the bar.
| Field |
Default |
What it does |
| Button at the end of the bar |
Off |
Adds the button to the end of the bar. |
| Button text |
“Get started” |
The words on the button. |
| Button link |
empty |
Where the button goes: a page, a file, an email address, a phone number, a blog or any web address. An empty link leaves the button off. |
| Hide the button on phones |
On |
Leaves the button out of the phone layout so the links keep the room. |
Behaviour
Sticking, jumping and the extras.
| Field |
Default |
What it does |
| Stay in view while scrolling |
On |
Off, the module stays where you put it and still marks the current section. |
| Stop sticking after the last section |
On |
The bar scrolls away once the last linked section has passed. Off keeps it until the end of the page. |
| Site header height |
Measure my sticky header |
Automatic looks for anything fixed or sticky at the top of the screen (your site header) and places the bar right under it. It checks again as the page scrolls and when the window is resized, so a header that shrinks on scroll is followed. Use a fixed number if your header is not detected or you want a different gap. |
| Header height |
0 px |
The distance from the top of the screen, in pixels, where the bar sticks and jumps end. |
| Space above a section after a jump |
0 px |
Extra room, in pixels, between the bar and the top of a section after a jump. |
| Smooth scrolling |
On |
Scrolls to the section instead of jumping there. Visitors whose device asks for reduced motion always jump. |
| Add the section to the address bar |
Off |
Writes the current section into the address bar (/page#pricing) without adding entries to the browser history, so the Back button still leaves the page. |
| Reading progress line on the bar |
Off |
A thin line along the bottom of the bar that fills as the reader scrolls down the page. |
| Hide while scrolling down, show when scrolling up |
Off |
While stuck, the bar slides away when the reader scrolls down and comes back when they scroll up. |
| A section becomes current when it is this far from the bar |
120 px |
How far below the bar, in pixels, a section’s top has to reach before its link becomes current. |
Words
Every word the module prints that is not a link.
| Field |
Default |
What it does |
| Name for screen readers |
“On this page” |
The name screen readers announce for the navigation, for example "On this page" or "Pricing sections". |
| Dropdown button text |
“Jump to…” |
The dropdown button’s words before the reader reaches the first section. After that the button shows the current section’s name. |
Field reference — Style tab
Colours
Every colour has an opacity slider.
| Field |
Default |
What it does |
| Background |
#ffffff at 92% |
The bar or rail background. Lower the opacity and the page shows through, blurred by Background blur. |
| Link text |
#525252 |
Links that are not current. |
| Link text on hover |
#0a0a0a |
A link under the pointer. |
| Current link text |
#0a0a0a |
The current link, and the dropdown button on phones. |
| Current link marker |
#0a0a0a |
The underline under the current link, and the marker on the rail. |
| Current pill and segment groove |
#f5f5f5 |
The background of the current pill, and the groove behind segments. |
| Current segment |
#ffffff |
The raised segment behind the current link, and the solid backing of the phone dropdown. |
| Border |
#e5e5e5 |
The line under the bar, the outline of the rail and the empty part of the rail's progress line. |
| Progress line |
#0a0a0a |
The reading progress line on the bar. |
| Button background |
#0a0a0a |
The button at the end of the bar. |
| Button text |
#ffffff |
The words on that button. |
Text
Text in the links, the button and the dropdown.
| Field |
Default |
What it does |
| Font |
Inherit |
Empty uses the font of the page around the module, so it follows your theme. |
| Text size |
15 px |
Link text size. Rail titles are 80% of it. |
| Weight |
Medium |
Links that are not current. |
| Current link weight |
Semibold |
The current link and the button. |
| Capital letters |
Off |
Shows the links in capital letters. |
| Letter spacing |
0 px |
Space between letters, in pixels. |
Sizes
Sizes in pixels.
| Field |
Default |
What it does |
| Bar height |
56 px |
The height of the bar and of each link in it. Pills and segments sit inside it. |
| Space inside each link |
14 px |
Space to the left and right of each link's words. |
| Space between links |
4 px |
Space between neighbouring links. |
| Link corner radius |
8 px |
Pills and segments. 999 makes a full pill. |
| Bar corner radius |
0 px |
Rounds the bar while it sits in the page; a stuck bar is always square. |
| Underline thickness |
2 px |
The underline, and the marker or progress line of the rail. |
| Border width |
1 px |
The line under the bar and around the rail. 0 removes it. |
| Progress line thickness |
2 px |
The reading progress line on the bar. |
| Rail width |
240 px |
The widest the rail gets. It never grows past its column. |
| Content width |
1200 px |
The links line up with this width when the bar spans the screen. |
| Side padding |
16 px |
Space at the left and right of the bar's content, and inside the rail. |
Effects
Shadow, blur, timing and stacking.
| Field |
Default |
What it does |
| Shadow while stuck |
Soft |
The shadow under the bar while it sticks. |
| Background blur |
12 px |
Only visible when the background is see-through. |
| Animation length |
200 ms |
Marker, hide and show. Reduced-motion visitors get none. |
| Stacking order |
40 |
Raise it if part of your page covers the bar; lower it if the bar covers your menu. |
For developers
Every class starts with section-nav-pro, and each instance's root has the id section-nav-pro-<module name>, which you
can use to override its styles without !important. Every colour and size is also a CSS variable on that root
(--section-nav-pro-bg, --section-nav-pro-active, --section-nav-pro-height and the rest).
- Event. When the current section changes, the module's root fires
section-nav-pro:change (it bubbles) with
detail.id (the section's anchor, or null above the first section) and detail.index.
- Headings added later. If your page adds content after it loads, call
window.sectionNavPro.refresh() to measure
again.
- Header height.
window.sectionNavPro.headerBottom() returns the bottom edge, in pixels, of the header the module found.
Troubleshooting
The bar hides behind my sticky header, or leaves a gap under it.
The module looks for a fixed or sticky element at the very top of the screen. A header that starts lower, is taller than
half the screen, or is see-through at the top can be missed. Set Site header height to a fixed number and
type your header's height in Header height. If the bar sits under part of the header that floats above
everything, raise Stacking order; if it covers your header's dropdown menus, lower it.
The bar never sticks.
Check the live or preview page; the page editor never sticks it. Then check Stay in view while scrolling. If it still
does not stick, your theme probably scrolls something other than the page itself: some themes set overflow: hidden on
html or body and scroll an inner wrapper instead (body { height: 100%; overflow: auto } or a full-screen
.body-wrapper). The module follows the page's own scroll, so it never sees that scrolling. Ask your theme developer to
let the page scroll normally (overflow-x: clip keeps the sideways protection without stopping vertical scrolling).
The stuck bar is in the wrong place or the wrong width.
A transform, filter or backdrop-filter on an element that contains the module changes what "fixed" means for
everything inside it. Remove that style from the section that holds the module, or place the module in a section without it.
The jump stops a little short or a little past the heading.
Use Space above a section after a jump to add room. If your header changes height as you scroll, the module corrects
after the scroll ends; a fixed Header height of the header's scrolled height makes it exact from the start.
A link is missing for visitors.
Its section anchor is not on the page. Open the page editor: the note above the module lists the anchors it could not
find. Check the spelling and the capital letters, and leave out the #.
Automatic mode shows too many or the wrong links.
Put the part of the page to read in Look only inside (for example #article or main), lower
Most links, or leave headings out with Skip headings matching or the data-section-nav-pro-skip
attribute. To shorten a long heading in the bar, add data-section-nav-pro-label="Short name" to the heading.
Automatic mode shows no links.
The page has no headings matching Headings to use (outside headers, footers and menus), or the scope
selector matches nothing. The editor note says which. Many themes use h2 for section headings; if yours uses h3, set
the selector to h3.
The section under the bar is wrong when a section is short.
A section becomes current when its top passes the line below the bar. Raise A section becomes current when it is this far from the bar to switch
earlier.
My theme's own smooth scrolling fights the jump.
The module handles clicks on its own links before the theme sees them, so theme scripts that animate # links leave
them alone.
FAQ
Do I need to add anchors to my sections?
Not with automatic mode: it makes the anchors from your headings. With your own list, each section needs an anchor (see
How anchors work in HubSpot).
Can I use it in a blog post?
Yes. Add it to the blog post template, or a drag-and-drop area in it, with automatic mode set to the post body (for
example Look only inside .blog-post__body or your theme's post body class). Each post then gets its own links.
Can I have more than one on a page?
Yes. Each instance has its own links and settings, and a later bar pushes an earlier one out of the way when it reaches
the header.
Does it work with dark themes?
Every colour is a field with opacity. Set the background, the text and the marker colours to match.
Will it slow the page down?
The module adds one small script and stylesheet and no outside requests. It does its work once per frame while scrolling.
Support
Email hello@studionope.com. Unlimited email support, answered within one business day, Monday to Friday, 9:00–17:00
EET. Please include the page address.
Notes on this page
Every navigation above is an instance of the module, on the same container as its text. Plotline is a made-up product, and its screens are mockups. The site header at the top of this page is sticky, like most themes' headers, and no CSS on this page touches the module.