Bootstrap Progress Bar Extension

Enhanced progress components with circular progress and animations for Bootstrap 5.

View Live Demo

Features

This package provides:

• Standard Bootstrap Progress Bar Extension with animation
• Custom circular progress bars
• Viewport-based animation triggers
• Configurable animation duration and delays
• Multiple color variants (primary, success, info, warning, danger)
• Stroke width customization for circular progress
• Built-in accessibility features
• Lightweight implementation (only ~325 lines of JS)
• Support for dynamically added progress bars

Installation

npm install bootstrap-progress-extension

Include the CSS and JavaScript files in your project:

<!-- For production -->
<link href="path/to/bootstrap-progress-extension.min.css" rel="stylesheet">
<script src="path/to/bootstrap-progress-extension.min.js"></script>

<!-- For development/debugging -->
<link href="path/to/bootstrap-progress-extension.css" rel="stylesheet">
<script src="path/to/bootstrap-progress-extension.js"></script>

Usage

Basic Progress Bar

<div class="progress" role="progressbar" aria-label="Basic example" 
     aria-valuenow="75" aria-valuemin="0" aria-valuemax="100"
     data-bs-config='{"duration": 2000}'>
  <div class="progress-bar"></div>
</div>

Circular Progress Bar

• Note: The <div class="progress-label">...</div> element is required within the .progress-bar for circular progress bars. Important: For circular progress bars, you only need to include the standard .progress and .progress-bar elements, along with a <div class="progress-label">...%</div> inside the .progress-bar. The decorative <div class="circle-background"></div> and <div class="circle-progress"></div> elements will be automatically injected by the script. Do not include them in your source HTML.

<div class="progress circular" role="progressbar" aria-label="Circular progress"
     aria-valuenow="75" aria-valuemin="0" aria-valuemax="100"
     data-bs-config='{"strokeWidth": 15, "animateInViewport": true}'>
  <div class="progress-bar bg-success">
    <div class="progress-label">75%</div>
    <!-- .circle-background and .circle-progress will be added here by the script -->
  </div>
</div>

RTL Support (Right-to-Left)

For RTL languages like Arabic, Hebrew, or Persian, simply wrap your progress bar in a container with dir="rtl":

<div dir="rtl">
  <!-- Circular Progress in RTL -->
  <div class="progress circular" role="progressbar" aria-label="تقدم دائري"
       aria-valuenow="65" aria-valuemin="0" aria-valuemax="100"
       data-bs-config='{"strokeWidth": 15, "duration": 2000}'>
    <div class="progress-bar bg-primary">
      <div class="circle-background"></div>
      <div class="circle-progress"></div>
      <div class="progress-label">٦٥٪</div>
    </div>
  </div>
  
  <!-- Standard Progress Bar in RTL -->
  <div class="progress" role="progressbar" aria-label="شريط التقدم"
       aria-valuenow="70" aria-valuemin="0" aria-valuemax="100"
       data-bs-config='{"duration": 1800}'>
    <div class="progress-bar bg-success"></div>
  </div>
</div>

Dynamic Creation

Progress bars added dynamically to the DOM after page load will be automatically initialized:

// Create a progress bar dynamically
const progressBar = document.createElement('div');
progressBar.className = 'progress';
progressBar.setAttribute('role', 'progressbar');
progressBar.setAttribute('aria-label', 'Dynamic progress');
progressBar.setAttribute('aria-valuenow', '60');
progressBar.setAttribute('aria-valuemin', '0');
progressBar.setAttribute('aria-valuemax', '100');

const bar = document.createElement('div');
bar.className = 'progress-bar bg-success';
bar.style.width = '0%';

progressBar.appendChild(bar);
document.body.appendChild(progressBar);
// No manual initialization needed - MutationObserver will detect and initialize it

Configuration Options

All progress components can be configured using the data-bs-config attribute with JSON:

CSS Variables

The appearance of the circular progress bars can be customized using the following CSS custom properties:

Note: While --arc-color and --progress-angle are used internally, you typically control the appearance via the data-bs-config options (size, strokeWidth) and standard Bootstrap background utility classes (bg-primary, bg-success, etc.) rather than setting these CSS variables directly.

Bootstrap Variable Usage

This extension leverages standard Bootstrap CSS variables for theming and consistency:

JavaScript API

Working with progress bars programmatically:

// Create a new progress bar instance
const progressElement = document.querySelector('.progress');
const progressBar = new ProgressBar(progressElement);

// Set value without animation
progressBar.setValue(75);

// Animate to value (target percentage, optional duration)
progressBar.animate(90, 2000);

// Initialize to 0%
progressBar.initialize();

Accessibility Features

Bootstrap Progress Bar Extension are built with accessibility in mind:

• ARIA Support: All progress bars use proper ARIA attributes (role="progressbar", aria-valuenow, aria-valuemin, aria-valuemax, and aria-label)
• Reduced Motion: Automatically respects the user's prefers-reduced-motion browser setting, disabling animations for users who prefer reduced motion
• Text Labels: Circular progress bars include visible text labels showing the current progress percentage
• Color Contrast: All components maintain proper contrast ratios between background, foreground, and text elements
• RTL Support: Full support for right-to-left languages using the dir="rtl" attribute
• Responsive Design: Components adapt to different screen sizes for usability on mobile devices

Browser Compatibility

• Chrome/Edge 60+
• Firefox 60+
• Safari 12+
• iOS 12+
• Not compatible with Internet Explorer

License

MIT