Turn scrolling into a clear visual journey.
Kinetic Scroll Progress is a Gutenberg block that shows visitors how far they have progressed through a page — from a simple reading progress bar to an advanced milestone-based journey with section tracking, navigation, responsive presentations, and visual effects.
Use it for:
- Blog posts and long-form articles
- Landing pages
- Documentation
- Product tours
- Service or process pages
- Case studies
- Storytelling pages
- Guided page journeys
The block stays fixed on the screen while the visitor scrolls, giving them an immediate visual sense of where they are and how much content remains.
What Does Kinetic Scroll Progress Do?
At its simplest, Kinetic Scroll Progress displays a thin bar that fills as the visitor moves down the page.
But it can do much more.
You can add milestones based on your page headings, show the current section, use a vertical journey instead of a horizontal bar, create different desktop and mobile layouts, or turn milestones into interactive navigation.
With KineticHub PRO, you can also track only a specific section of the page, manually define milestone targets, use circular or segmented presentations, and add enhanced visual effects through Smart Addons.
A simple example
Imagine a long article with five main sections.
A standard progress bar shows:
0% → 25% → 50% → 75% → 100%
Enable milestones and the same indicator can also show:
Introduction → Features → Examples → FAQ → Conclusion
As the visitor scrolls, the current milestone updates automatically.
Quick Start
For a basic page progress indicator:
- Add the Kinetic Scroll Progress block to your page.
- Choose Horizontal Bar as the Presentation.
- Choose Top as the Screen Position.
- Select your Track and Progress colors.
- Adjust Thickness if needed.
- Save the page and view it on the frontend.
That is enough to create a complete page progress indicator.
Tip: The editor displays a preview of the block, but real scroll tracking happens on the frontend.
1. Presentations
Kinetic Scroll Progress can display progress in several visual formats.
Horizontal Bar
Available in FREE
A horizontal progress bar fixed to the top or bottom of the screen.
This is the most familiar presentation and works especially well for:
- Articles
- Blog posts
- Landing pages
- Long sales pages
- Documentation pages
The bar fills horizontally as the visitor scrolls.
Recommended use
For most websites, start with:
- Presentation: Horizontal Bar
- Position: Top
- A thin 3–5px indicator
- A subtle Track Color
- Your brand color as Progress Color
This creates a clean progress indicator without competing with the page content.
Vertical Rail
Available in FREE
A vertical progress indicator fixed to the left or right side of the screen.
Vertical Rail is particularly useful when milestones are enabled because it can make the page feel like a guided journey rather than a simple reading progress bar.
Good for:
- Documentation
- Product tours
- Step-by-step pages
- Case studies
- Long service pages
- Storytelling layouts
Tip: Vertical Rail usually works best on wider desktop layouts. On smaller screens, consider simplifying milestone labels or using a different Mobile Presentation with PRO.
Floating Ring
KineticHub PRO
Floating Ring displays progress as a compact circular indicator in one of the four corners of the screen.
Instead of occupying an entire screen edge, it gives you a self-contained progress widget.
You can control:
- Ring Corner
- Ring Size
- Ring Size on Mobile
- Ring Thickness
- Direction
- Colors
- Progress effects
The ring begins at the top and fills around the circle as the visitor progresses.
If Direction is reversed, the ring fills in the opposite direction while keeping its starting point at the top.
Ring thickness protection
If you combine a very thick stroke with a very small ring, Kinetic Scroll Progress automatically keeps the ring within safe visual limits rather than allowing the stroke to overflow.
Milestones and Floating Ring
Floating Ring does not display milestone markers or milestone labels.
This is intentional: the ring is designed as a compact progress presentation.
Your milestone settings are not deleted. If you switch the presentation back to Horizontal Bar or Vertical Rail, they become available again.
Segmented Progress
KineticHub PRO
Segmented Progress divides the indicator into individual pieces instead of drawing one continuous bar.
For example:
▰ ▰ ▰ ▰ ▱ ▱ ▱ ▱
Completed segments light up as the visitor moves through the page.
You can choose between 3 and 30 segments.
Important: Segments and milestones are different
The number of segments is independent of your milestone count.
You might have:
- 10 visual segments
- 5 milestone headings
or:
- 20 visual segments
- 8 milestones
They serve different purposes.
Segmented Progress can be positioned on all four edges:
- Top
- Bottom
- Left
- Right
Top and Bottom create a horizontal segmented indicator. Left and Right create a vertical segmented rail.
2. Mobile Presentation
KineticHub PRO
Desktop and mobile do not always need the same progress indicator.
Mobile Presentation lets you automatically switch to another presentation at 768px and below.
For example:
Desktop: Vertical Rail
Mobile: Horizontal Bar
or:
Desktop: Floating Ring
Mobile: Horizontal Bar
or:
Desktop: Segmented Progress
Mobile: Floating Ring
The default is Same as Desktop, so nothing changes unless you choose a separate mobile presentation.
Kinetic Scroll Progress automatically adapts the screen edge when switching between presentations where necessary.
Recommended mobile strategy
If your desktop layout uses many milestone labels, a simpler mobile presentation is usually easier to read.
A strong combination is:
Desktop
- Vertical Rail
- H2 + H3 milestones
- Labels visible
Mobile
- Horizontal Bar
- H2 milestones only
- Current label only
3. Progress Source
By default, the indicator measures progress through the entire page.
Entire Page
The standard behavior.
Progress begins near the start of the document and reaches 100% when the visitor reaches the end of the page.
This is appropriate for most:
- Articles
- Landing pages
- Blog posts
- Documentation pages
No additional configuration is required.
Track Only Part of a Page
KineticHub PRO
Progress Source allows the indicator to represent a specific section instead of the entire document.
Available tracked-source workflows include:
Parent Section
The indicator follows the nearest relevant parent section around the Scroll Progress block.
This is useful when the indicator belongs to a particular:
- Section
- Group
- Cover
- Columns area
- Long content region
Instead of saying “you are 40% through the entire webpage,” the indicator can say “you are 40% through this experience.”
Custom CSS Selector
Track any matching element using a CSS selector.
Examples:
.product-tour
#documentation
.case-study-content
The first matching element becomes the tracked progress source.
Safe fallback
If a Custom CSS Selector is invalid or no matching element can be found, Kinetic Scroll Progress safely falls back to whole-page progress.
It does not leave the visitor with a broken or permanently hidden indicator.
Visibility while tracking a section
When a specific section or selector is being tracked, the indicator is relevant only while that area is being viewed.
It can stay out of the way before the tracked content is reached, appear while the visitor moves through that content, and leave once the tracked area has been passed.
4. Screen Position
Choose where the indicator appears on the screen.
Available edges include:
- Top
- Bottom
- Left
- Right
The most appropriate positions depend on the Presentation.
Top
Best for:
- Reading progress
- Articles
- Landing pages
Bottom
Useful when the top of the site already contains a strong sticky header or navigation system.
Left / Right
Ideal for:
- Vertical Rail
- Milestone journeys
- Documentation
- Product tours
5. Size and Placement
You can fine-tune how much visual space the indicator uses.
Controls include desktop and responsive values where appropriate.
Thickness
Controls how thick the progress indicator appears.
A small value produces a subtle progress line.
A larger value creates a stronger visual element.
Mobile Thickness
Use a separate thickness on smaller screens.
A thinner mobile indicator often prevents the progress UI from competing with the page content.
Length / Width
Control how much of the available screen edge the indicator occupies.
It does not need to stretch across the entire viewport.
A shorter centered indicator can create a more designed, editorial appearance.
Distance from Edge
Moves the indicator inward from its selected screen edge.
This is particularly useful when your website has:
- A sticky header
- Floating navigation
- Cookie controls
- Other fixed interface elements
Distance from Edge on Mobile
Provides a separate mobile offset.
Layer (z-index)
Controls the stacking level of the progress indicator.
Increase it if another theme element incorrectly covers the indicator.
Lower it if you want another fixed interface element to remain above it.
Sticky header tip
Kinetic Scroll Progress includes positioning safeguards for common top-of-screen situations, including the WordPress admin toolbar.
However, every theme handles sticky headers differently.
If your theme header overlaps the indicator, increase Distance from Edge until the progress indicator sits below it.
6. Colors and Shape
The indicator can be styled to match your site’s branding.
Track Color
The Track is the uncompleted portion of the indicator.
A subtle or transparent color usually works best.
Progress Color
The Progress Color represents the completed portion.
This is normally the stronger color and is a good place to use your brand accent.
Track Opacity
Adjust how visible the unfinished track should be.
Lower opacity creates a more minimal look.
Progress Opacity
Adjust the visual strength of the completed progress area.
Border Radius
Controls the roundness of the bar or rail.
Use a larger radius for a softer pill-like appearance, or a smaller radius for a sharper interface style.
Direction
Choose the direction in which progress fills.
Use the normal direction for standard progress behavior or Reverse when the design requires the visual movement to travel in the opposite direction.
7. Smoothing
Smoothing controls how closely the visual indicator follows the raw scroll position.
Available behaviors include:
None
The indicator follows the current scroll progress directly.
Best when you want the most immediate response.
Subtle
Adds a small amount of visual smoothing.
A good balance for most designs.
Smooth
Creates a softer following motion.
Useful when the progress indicator is a stronger visual part of the page design.
Accessibility: Visitors who request reduced motion through their operating system do not receive unnecessary interpolation or decorative motion.
8. Milestones
Milestones transform the progress indicator from a simple percentage into a visual page journey.
Instead of showing only how far the visitor has scrolled, milestones can represent the sections they are moving through.
For example:
Overview → Features → Examples → Pricing → FAQ
Milestones can include:
- Markers
- Labels
- Current-state highlighting
- Completed states
- Responsive label behavior
Enable Milestones
Turn milestones on to add section markers to supported presentations.
Milestones are available with bar and rail presentations.
Floating Ring does not display them.
9. Automatic Milestones from Headings
The easiest way to build a milestone journey is to let Kinetic Scroll Progress read your page headings automatically.
You decide which heading levels should participate.
For example:
H2 only
Tracks major page sections.
Best for simpler or shorter journeys.
H2 + H3
Tracks both primary and secondary sections.
Useful for detailed documentation or long pages.
Why heading levels matter
A page containing many H2, H3 and H4 headings can create too many milestones.
In most designs, the milestone journey should represent important sections rather than every small heading.
10. Milestone Density
Use Maximum Milestones to limit how many milestones appear.
Desktop and mobile can use different limits.
This is especially important for responsive layouts.
Recommended starting point
Desktop
- Heading Levels: H2 + H3
- Maximum Milestones: 12
Mobile
- Heading Levels: H2
- Maximum Milestones: 6
When the viewport changes between desktop and mobile, Kinetic Scroll Progress can re-evaluate the milestone selection for the appropriate device layout.
11. Milestone Markers
Choose how each milestone is represented.
Dot
Displays milestones as dots along the progress journey.
A good choice when you want a clean and modern indicator.
Tick
Uses tick-style markers.
Useful when you want a more structured or timeline-like appearance.
You can also control the colors used for reached and upcoming milestones.
12. Milestone Labels
Milestone labels help visitors understand what each point represents.
The label normally comes from the relevant page heading.
Different display strategies are available to prevent crowded layouts.
Show
Displays the available milestone labels.
Best when there are only a few milestones and enough space.
Major Headings Only
Shows labels for the most important heading level while still allowing smaller milestones to remain represented.
This is useful on detailed documentation pages.
Current Only
Shows only the label for the section the visitor is currently reading.
This is one of the best options for mobile because it provides context without filling the screen with text.
Hide
Hides milestone labels while keeping the progress markers.
13. Horizontal Label Layout
Horizontal indicators can become crowded when several labels are displayed.
Use the horizontal label layout controls to manage the available space.
Staggered Labels
Staggering distributes labels across alternating rows, giving longer milestone journeys more room.
This is useful when:
- Several labels are visible
- Heading names are longer
- The horizontal bar spans a limited width
Kinetic Scroll Progress automatically accounts for the additional label space so the journey remains positioned correctly.
14. Milestone Label Background
Labels can receive their own background treatment to improve readability.
Available visual treatments include styles such as:
- Box
- Rounded
- Pill
Use these when milestone text needs additional contrast against the page behind it.
You can also control the Label Background color.
Sync Background with Progress
When enabled, milestone backgrounds can visually follow the progress state.
Upcoming milestones use the track styling, while reached/current milestones use the progress styling.
This creates a clearer relationship between the labels and the progress journey.
15. Manual Milestones
KineticHub PRO
Automatic headings are convenient, but sometimes your page journey does not match the document heading structure.
Manual Milestones give you complete control.
Each manual milestone can contain:
- A CSS selector target
- An optional custom label
You can create up to 30 manual milestones per indicator.
You can also:
- Add milestones
- Remove milestones
- Reorder them in the editor
Actual page position determines the journey
The frontend sorts valid targets according to where they actually appear on the page.
This means your milestone journey still follows the page correctly even if the editor list was entered in another order.
Invalid targets
A manual milestone is safely skipped when its target:
- Does not exist
- Uses an invalid selector
- Is hidden on the current screen
If two manual milestones point to the same page element, the target is not unnecessarily represented twice.
Manual milestones with Progress Source
If you are tracking only a particular section, manual milestone targets are scoped to that tracked area.
This keeps the milestone journey consistent with the progress being measured.
16. Milestone Navigation
KineticHub PRO
Milestones can become interactive navigation controls.
Enable Milestone Navigation and visitors can select a milestone to move directly to the corresponding section.
This is useful for:
- Documentation
- Product tours
- Long service pages
- Feature walkthroughs
- Interactive contents-style navigation
Navigation works with:
- Automatic heading milestones
- Manual milestones
Keyboard navigation
Interactive milestones support keyboard activation.
When a milestone is activated, focus is moved appropriately to the destination content, making the journey usable beyond pointer interaction.
The current milestone is also represented semantically for navigation state.
Reduced motion
If a visitor has requested reduced motion, milestone navigation uses an immediate jump rather than forcing an animated scroll.
URL behavior
Milestone Navigation does not need to rewrite the page URL or generate artificial heading IDs to work.
17. Smart Addons
KineticHub PRO
Smart Addons add optional visual polish without changing the underlying progress logic.
Use them selectively. A clean progress indicator often needs only one or two enhancements.
Progress Glow
Adds a glow using your existing Progress Color.
Options:
- None
- Soft
- Strong
Progress Glow works across the different presentations.
On Floating Ring, the glow follows the progress arc.
On Segmented Progress, it follows the active segments.
Recommended: Start with Soft. Strong works better when the indicator is intentionally part of the visual design.
Active Label Emphasis
Adds visual emphasis to the currently active milestone label.
Options:
- None
- Scale
- Glow
This feature requires milestone labels to be visible.
Use it when visitors need a stronger indication of the section they are currently reading.
Current Milestone Pulse
Adds a slow halo effect to the current milestone marker.
Options:
- None
- Subtle
- Noticeable
Only the current milestone receives the effect.
For most professional layouts, Subtle is the safest starting point.
Completed Milestone Style
Changes the appearance of milestones the visitor has already passed.
Options:
- Default
- Outline
- Check
The Check treatment is intended for Dot markers.
If you are using Tick markers, their existing tick presentation remains the more appropriate visual representation.
Dual Ring
Available when Floating Ring is being used.
Dual Ring adds a second inner progress ring for additional depth.
This works well when the Floating Ring is intended to feel like a standalone interface element rather than a minimal reading indicator.
Ring Center Content
Available with Floating Ring.
Displays the current scroll percentage inside the ring.
For example:
64%
This turns the ring into a compact numerical progress widget.
18. Responsive Setup
Kinetic Scroll Progress includes separate responsive controls where they provide practical value.
You can simplify mobile layouts using:
- Mobile Thickness
- Mobile sizing
- Mobile distance from edge
- Mobile heading levels
- Mobile Maximum Milestones
- Mobile label behavior
- Hide on Mobile
- A separate Mobile Presentation with PRO
Why mobile should usually be simpler
A milestone journey that looks excellent across a 1440px desktop can become crowded on a 360px phone.
Instead of shrinking everything, simplify the information.
For example:
Desktop
- Vertical Rail
- H2 + H3
- Maximum Milestones: 12
- Labels: Major Headings Only
Mobile
- Horizontal Bar
- H2
- Maximum Milestones: 6
- Labels: Current Only
This preserves the useful context without covering the content.
19. Device Visibility
Use the Visibility controls when an indicator should only appear on particular devices.
Options include:
- Hide on Mobile
- Hide on Desktop
This is useful if you prefer two separate Scroll Progress instances with completely different configurations.
For example:
Desktop instance
- Vertical Rail on the right
Mobile instance
- Simple Horizontal Bar at the bottom
Multiple Scroll Progress blocks can be used on the same page.
If you use multiple indicators at once, place them on different edges to avoid visual overlap.
20. Accessibility
Kinetic Scroll Progress is designed so that decorative progress does not create unnecessary noise for assistive technology.
Passive progress indicator
A standard non-interactive progress indicator visually repeats information that already exists through the visitor’s position on the page.
For that reason, the decorative output is not continuously announced by screen readers while the visitor scrolls.
Reduced motion
Kinetic Scroll Progress respects the visitor’s prefers-reduced-motion preference.
When reduced motion is requested:
- Progress still updates
- Milestone states still update
- Unnecessary transitions are removed
- Decorative animations are disabled
- Milestone navigation uses an immediate jump
The functionality remains available without requiring animated movement.
Interactive milestone navigation
When Milestone Navigation is enabled, the relevant controls support keyboard interaction and focus handling so they can operate as real navigation rather than pointer-only decoration.
21. Editor Preview
The Gutenberg editor displays a static preview of Kinetic Scroll Progress.
The preview helps you configure:
- Presentation
- Colors
- Thickness
- Border radius
- Direction
- Milestones
- Labels
- Smart Addons
The editor preview intentionally does not track scrolling inside the WordPress editor.
Real behavior such as:
- Fixed positioning
- Page progress
- Section tracking
- Current milestones
- Navigation
- Responsive presentation switching
should be checked on the frontend.
Tip: If a setting appears static in the editor, preview or open the published page before assuming it is not working.
22. Performance
Kinetic Scroll Progress was built for pages where scrolling itself must remain smooth.
The frontend runtime avoids unnecessary work and does not depend on a third-party animation library.
When multiple Scroll Progress indicators exist on the same page, they can share the same scroll-processing system rather than each creating an independent scroll engine.
The block uses:
- A shared scroll listener
- Scheduled frame updates
- Cached page geometry
- Geometry refreshes when the viewport or relevant content changes
- No permanent
will-changerequirement - No third-party animation framework
It also accounts for common layout changes such as:
- Window resize
- Orientation changes
- Late-loading media
- Web fonts
- Content size changes
- Dynamically inserted content
This allows the progress indicator to remain accurate without continuously performing expensive page measurements during every scroll event.
23. Recommended Setups
Setup A — Simple Reading Progress
Best for blog posts and articles.
Presentation: Horizontal Bar
Position: Top
Thickness: 3–4px
Milestones: Off
Smoothing: Subtle
Progress Glow: None or Soft
Result: a minimal reading progress indicator with almost no visual distraction.
Setup B — Documentation Journey
Best for documentation and structured long-form content.
Presentation: Vertical Rail
Position: Right
Milestones: On
Desktop Headings: H2 + H3
Desktop Maximum: 12
Desktop Labels: Major Headings Only
Mobile Headings: H2
Mobile Maximum: 6
Mobile Labels: Current Only
With PRO, enable Milestone Navigation to turn the journey into an interactive section navigator.
Setup C — Product Tour
Best for feature walkthroughs and guided landing pages.
Presentation: Vertical Rail or Segmented Progress
Milestones: On
Milestone Source: Manual if your sections do not follow heading structure
Progress Source: Parent Section or Custom CSS Selector
Navigation: On
Current Milestone Pulse: Subtle
Completed Style: Outline or Check
Result: the progress UI represents the product tour itself instead of the entire webpage.
Setup D — Compact Floating Progress
KineticHub PRO
Best when you want progress without reserving a complete screen edge.
Presentation: Floating Ring
Corner: Bottom Right
Ring Center Content: Percentage
Progress Glow: Soft
Dual Ring: Optional
Result: a compact floating progress widget.
Setup E — Clean Mobile Experience
For pages with many desktop milestones.
Desktop: Vertical Rail with milestone labels
Mobile Presentation: Horizontal Bar
Mobile Headings: H2 only
Maximum Milestones: 6
Labels: Current Only
This is usually more readable than forcing the full desktop journey onto a narrow screen.
24. Troubleshooting
The indicator overlaps my sticky header
Increase Distance from Edge.
If necessary, also adjust Layer (z-index) depending on how your theme handles its sticky header.
I have too many milestone labels
Try one or more of the following:
- Track H2 headings only
- Reduce Maximum Milestones
- Use Major Headings Only
- Use Current Only
- Use Staggered Labels
- Simplify the mobile configuration
Floating Ring does not show milestones
This is intentional.
Floating Ring is a compact progress-only presentation and does not draw milestone markers or labels.
Your milestone settings remain saved and return if that viewport uses Horizontal Bar, Vertical Rail, or another milestone-compatible presentation.
My manual milestone is missing
Check that:
- The CSS selector is valid.
- The target exists on the page.
- The target is visible on the current device.
- If using a custom Progress Source, the milestone target belongs to that tracked area.
Invalid or unavailable targets are skipped safely.
My Custom CSS Selector does not seem to work
Check the selector in your browser or theme markup.
If the selector is invalid or matches nothing, Kinetic Scroll Progress deliberately falls back to whole-page progress rather than breaking the indicator.
My changes do not animate in the editor
The Gutenberg preview is intentionally static.
Open Preview or view the frontend page to test actual scrolling behavior.
Completed Style: Check does not change my Tick markers
The Check treatment is designed for Dot markers.
Tick markers already use their own tick presentation.
The mobile milestone journey is crowded
Reduce the amount of information rather than simply shrinking it.
Try:
- H2 only
- Maximum Milestones: 6
- Labels: Current Only
- Hide labels
- A simpler Mobile Presentation with PRO
My Segments count does not match my milestone count
That is expected.
Segments and milestones are independent systems.
Segments divide visual progress into pieces. Milestones represent meaningful locations in your content.
25. Frequently Asked Questions
Do I need milestones to use Scroll Progress?
No.
A standard Horizontal Bar or Vertical Rail can work as a simple page progress indicator with milestones completely disabled.
Does the block have to be placed at the top of the page?
No.
Its frontend presentation is fixed to the chosen screen position.
For whole-page progress, you can place the Gutenberg block wherever it is convenient in your page structure.
When using Parent Section as a PRO Progress Source, placement matters because the block uses its surrounding section as the tracked area.
Can I use more than one Scroll Progress block on a page?
Yes.
Multiple indicators are supported.
For the clearest result, give simultaneous indicators different screen positions so they do not overlap.
Can I track only one part of a page?
Yes, with KineticHub PRO.
Use Progress Source with Parent Section or a Custom CSS Selector.
Can visitors click milestones?
Yes, with KineticHub PRO.
Enable Milestone Navigation to turn the milestone journey into interactive section navigation.
Can I create milestones without using page headings?
Yes, with KineticHub PRO.
Choose Manual Milestones and provide CSS selector targets with optional custom labels.
Can desktop and mobile use different designs?
Yes.
Core responsive controls let you adapt size, density, labels, and visibility.
With KineticHub PRO, Mobile Presentation can also switch the entire presentation type at 768px and below.
Does Scroll Progress support reduced motion?
Yes.
The progress information remains functional while unnecessary transitions and decorative animation are removed for visitors who request reduced motion.
Final Recommendation
If you are using Kinetic Scroll Progress for the first time, do not start with every option enabled.
Begin with:
Horizontal Bar → Top → Subtle Smoothing → Brand Progress Color
Then decide whether your page benefits from milestones.
For structured content such as documentation or product tours, add milestone labels and responsive density controls.
Use the PRO tracking, navigation, alternate presentations, and Smart Addons when you want the progress indicator to become part of the page experience itself rather than simply show reading progress.
The goal is not to make visitors notice the progress indicator.
The goal is to make a long page feel easier to understand, easier to navigate, and easier to finish.