Enjoying these plugins? ☕ Buy me a coffee to support ongoing development.

Reading Progress Bar

A lightweight WordPress plugin that adds a visual reading progress bar to your posts, showing readers how far they've scrolled through the content.

Single File v1.0.0 Updated 1 month ago
View on GitHub Download

YT Reading Progress Bar

A lightweight WordPress plugin that adds a visual reading progress bar to your posts, showing readers how far they've scrolled through the content.

Features

  • Visual Progress Indicator: Shows a progress bar that fills as users scroll through content
  • Customizable Appearance: Choose color, height, and position of the bar
  • Optional Percentage Display: Show numeric reading percentage on the bar
  • Post Type Selection: Enable on posts, pages, or any custom post type
  • Top or Bottom Position: Place the bar at top or bottom of viewport
  • Smooth Animation: Silky smooth progress updates using throttled scroll events
  • Performance Optimized: Uses requestAnimationFrame and passive event listeners
  • Responsive Design: Works perfectly on desktop and mobile devices
  • Accessibility Friendly: Respects reduced motion preferences
  • Live Preview: See changes in real-time in the admin settings page
  • WPCS Compliant: Follows WordPress coding standards

Installation

  1. Upload the yt-reading-progress-bar folder to the /wp-content/plugins/ directory
  2. Activate the plugin through the 'Plugins' menu in WordPress
  3. Configure settings at Settings → Progress Bar
  4. The progress bar will automatically appear on selected post types

How It Works

Reading Progress Calculation

The plugin calculates reading progress using:

  • Scroll Position: Current vertical scroll position (window.pageYOffset)
  • Document Height: Total scrollable height of the page
  • Viewport Height: Height of the browser window
  • Formula: (scrollTop / (docHeight - viewportHeight)) * 100

Real-Time Updates

  • Scroll Listener: Throttled to update every 50ms for performance
  • Resize Listener: Recalculates on window resize
  • Dynamic Content: Watches for content changes using MutationObserver
  • Page Load: Updates after full page load for accurate calculations

Settings

Navigate to Settings → Progress Bar to configure:

Display Settings

  1. Enable Progress Bar

    • Toggle the progress bar on/off globally
    • Default: ✓ Enabled

  2. Bar Color

    • Color picker for the progress bar
    • Default: #2271b1 (WordPress blue)
    • Supports hex color codes

  3. Bar Height

    • Height in pixels (1-20px)
    • Default: 4px
    • Adjustable via number input

  4. Bar Position

    • Top: Fixed to top of viewport
    • Bottom: Fixed to bottom of viewport
    • Default: Top

  5. Post Types

    • Select where the bar should appear
    • Options: Posts, Pages, Custom Post Types
    • Default: Posts only

  6. Show Percentage

    • Display numeric percentage on the bar
    • Shows current reading progress (0-100%)
    • Default: ✗ Disabled

Live Preview

The settings page includes a live preview showing:

  • Current bar color
  • Current bar height
  • How the bar will look on your site

Changes to color and height update the preview in real-time!

Usage Examples

Basic Setup (Posts Only)

Default configuration works out of the box:

  • Appears on single posts
  • Blue bar at the top
  • 4px height
  • No percentage display

Enable on Multiple Post Types

  1. Go to Settings → Progress Bar
  2. Check "Posts", "Pages", and any custom post types
  3. Save changes
  4. Bar appears on all selected post types

Customize Appearance

  1. Click the color picker
  2. Choose your brand color (e.g., #ff6b6b)
  3. Adjust height to 6 for a thicker bar
  4. Select "Bottom" position
  5. Save changes

Show Reading Percentage

  1. Check "Show Percentage"
  2. Save changes
  3. A percentage indicator appears on the right side of the bar
  4. Updates in real-time as users scroll

File Structure

yt-reading-progress-bar/
├── class-yt-reading-progress-bar.php    # Main plugin file (~550 lines)
├── assets/
│   ├── css/
│   │   └── yt-reading-progress-bar.css  # Progress bar styles
│   └── js/
│       └── yt-reading-progress-bar.js   # Scroll tracking
└── README.md                             # This file

Prefix Convention

All functions, classes, and elements use the yt_reading_progress_bar prefix:

  • Class: YT_Reading_Progress_Bar
  • Constants: YT_READING_PROGRESS_BAR_*
  • Functions: yt_reading_progress_bar_*
  • CSS Classes: .yt-reading-progress-bar-*
  • JavaScript Object: ytReadingProgressBar
  • Options: yt_reading_progress_bar_options
  • Text Domain: yt-reading-progress-bar

Technical Details

CSS Implementation

  • Fixed Positioning: Bar stays in view during scroll
  • Z-Index: Set to 99999 to appear above all content
  • Pointer Events: Disabled so bar doesn't interfere with clicks
  • Transitions: Smooth width changes with 0.1s ease-out
  • Will-Change: Optimizes rendering performance

JavaScript Implementation

  • Vanilla JS: No jQuery dependency (though loaded for color picker in admin)
  • Throttled Events: Updates every 50ms maximum
  • Passive Listeners: Better scroll performance
  • Mutation Observer: Detects dynamic content changes
  • RequestAnimationFrame: Smooth visual updates

Performance Optimizations

  1. Throttling: Limits scroll event processing
  2. Passive Events: Doesn't block scrolling
  3. Will-Change: GPU acceleration for smooth animation
  4. Minimal Repaints: Only width property changes
  5. Efficient Calculations: Cached document height

Browser Support

  • Chrome (latest)
  • Firefox (latest)
  • Safari (latest)
  • Edge (latest)
  • Mobile browsers (iOS Safari, Chrome Mobile)
  • Internet Explorer 11+ (basic support, no fancy features)

Accessibility

  • Reduced Motion: Respects prefers-reduced-motion preference
  • High Contrast: Supports prefers-contrast: high mode
  • Screen Readers: Bar is visual only, doesn't interfere with content
  • Keyboard Navigation: Doesn't trap focus or interfere with keyboard

Styling

Default Styles

The plugin includes:

  • Clean, minimal design
  • Smooth animations
  • Shadow for depth
  • Mobile-responsive
  • Dark mode support

Custom Styling

Override styles in your theme:

.yt-reading-progress-bar {
    height: 8px !important;
    background: linear-gradient(to right, #667eea, #764ba2) !important;
    box-shadow: 0 4px 8px rgba(0, 0, 0, 0.2) !important;
}

.yt-reading-progress-percentage {
    font-size: 12px !important;
    background: rgba(0, 0, 0, 0.5) !important;
    padding: 4px 8px !important;
}

Admin Features

Color Picker

  • Uses WordPress core color picker (wp-color-picker)
  • Live preview updates on color change
  • Supports hex color codes
  • Fallback to text input if picker fails

Live Preview

  • Visual representation of the bar
  • Updates in real-time as you adjust settings
  • Shows actual color and height
  • Set to 60% width for demonstration

Troubleshooting

Progress bar not appearing?

  1. Check if enabled: Verify "Enable Progress Bar" is checked
  2. Check post type: Ensure current post type is selected in settings
  3. Check if singular: Bar only shows on single posts/pages, not archives
  4. Clear cache: Clear any caching plugins or CDN cache
  5. Check theme: Some themes might have conflicting z-index

Progress calculation seems off?

  1. Dynamic content: If you have lazy-loading, progress updates automatically
  2. Fixed headers: Very tall fixed headers might affect calculation
  3. Iframe content: Content in iframes isn't counted
  4. Hidden content: Collapsed accordions might affect height

Bar appears behind content?

  1. Z-index conflict: Theme might have higher z-index
  2. Custom CSS: Add z-index: 999999 !important; to .yt-reading-progress-bar-container
  3. Sticky elements: Some sticky elements might overlap

Percentage not showing?

  1. Check setting: Ensure "Show Percentage" is enabled
  2. JavaScript: Verify JavaScript is enabled in browser
  3. Console errors: Check browser console for errors
  4. Cache: Clear browser and plugin cache

Performance Impact

The plugin is highly optimized:

  • JavaScript: ~3KB minified
  • CSS: ~1KB minified
  • No external dependencies: Uses native browser APIs
  • Minimal DOM manipulation: Only updates width property
  • Throttled events: Maximum 20 updates per second
  • Passive listeners: Doesn't block scrolling

Best Practices

  1. Choose subtle colors: Don't distract from content
  2. Keep height reasonable: 3-6px works best
  3. Test on mobile: Ensure it looks good on small screens
  4. Consider position: Top is more noticeable, bottom less intrusive
  5. Use percentage sparingly: Only if users benefit from exact numbers

Uninstallation

When the plugin is deleted via WordPress admin:

  1. All plugin options are removed
  2. No database tables created (nothing to clean)
  3. WordPress cache is flushed
  4. No traces left behind

Requirements

  • WordPress 5.8 or higher
  • PHP 7.4 or higher
  • Modern browser with JavaScript enabled
  • No jQuery required (only for admin color picker)

Complexity

  • Main PHP File: ~550 lines (with comments)
  • CSS File: ~105 lines
  • JS File: ~155 lines
  • Total: ~810 lines across all files

FAQ

Does it work with page builders?

Yes! Works with Gutenberg, Elementor, Divi, Beaver Builder, and other page builders.

Does it affect SEO?

No impact on SEO. The progress bar is purely visual and doesn't modify content.

Can I use it on archive pages?

No, it's designed for single posts/pages. Archive pages don't have a clear "reading" concept.

Does it work with AMP?

Not automatically. AMP has strict JavaScript limitations.

Can I have different colors per post type?

Not in the lite version. All post types use the same color setting.

Does it work with infinite scroll?

Yes, if the infinite scroll updates the URL and loads new singular pages.

Will it slow down my site?

No! The plugin is highly optimized with throttled events and passive listeners.

Can I disable it on specific posts?

Not via UI, but you can use the yt_reading_progress_bar_should_display filter in your theme.

Changelog

1.0.0

  • Initial release
  • Reading progress bar with scroll tracking
  • Customizable color, height, and position
  • Optional percentage display
  • Post type selection
  • Live preview in admin
  • Responsive design
  • Accessibility features
  • Performance optimizations

License

GPL v2 or later

Author

Krasen Slavov

Support

For issues and feature requests, please visit the GitHub repository.

Future Enhancements

Potential features for future versions:

  • Multiple color schemes per post type
  • Animation effects (fade, slide, etc.)
  • Reading time estimate
  • Progress milestones (25%, 50%, 75%)
  • Integration with analytics
  • Custom positioning (left, right sides)
  • Gradient color support
  • Multiple bar styles (flat, rounded, gradient)

Related Plugins