bootstrap-progress-extension

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:

Option	Type	Default	Description
strokeWidth	Number	15	Sets the stroke width in pixels for circular progress bars
size	Number	120	Sets the size in pixels for circular progress bars
duration	Number	1500	Animation duration in milliseconds
delay	Number	0	Delay before animation starts in milliseconds
animation	Boolean	false	Whether to animate the progress. Set to true to enable animation.
animateInViewport	Boolean	true	Only animate when the element enters the viewport

CSS Variables

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

Variable	Description	Default Value	Controlled By
--circle-size	The overall width and height of the circular progress component.	120px	size config option
--circle-thickness	The thickness of the progress ring.	15px	strokeWidth config option
--arc-color	The color of the progress arc. Determined by bg-* classes.	var(--bs-progress-bar-bg)	bg-* CSS class
--progress-angle	The calculated angle (0-360deg) representing the current progress visually.	0deg	JavaScript (setValue)

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:

Bootstrap Variable	How It's Used
--bs-progress-bg	Background color for the track of standard progress bars and the inactive portion of the circular progress ring.
--bs-progress-bar-bg	Default color for the active arc of circular progress bars (used when no specific bg-* class is applied).
--bs-success	Color for the active arc when .bg-success is used on the circular progress bar.
--bs-danger	Color for the active arc when .bg-danger is used on the circular progress bar.
--bs-warning	Color for the active arc when .bg-warning is used on the circular progress bar.
--bs-info	Color for the active arc when .bg-info is used on the circular progress bar.
--bs-body-bg	Background color used for the inner cutout area of the circular progress bar (to match the page background).
--bs-body-color	Default text color for the percentage label inside circular progress bars.
--bs-dark	Text color used for the percentage label specifically when the circular progress bar has the .bg-light class.

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