### Install Development Dependencies
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/docs/contributing.md
Install the necessary tools for development, including npm packages and global command-line utilities like watchify and browserify.
```bash
npm install
npm install -g watchify
npm install -g browserify
```
--------------------------------
### Basic Usage Example
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/00-START-HERE.txt
A simple example demonstrating how to create, animate, and control a progress bar.
```APIDOC
## Basic Usage Example
### Description
A simple example demonstrating how to create, animate, and control a progress bar.
### Steps
1. **Create a progress bar**:
```javascript
var circle = new ProgressBar.Circle('#container', {
color: '#3498db',
strokeWidth: 4,
trailColor: '#ecf0f1',
text: { value: '0%' }
});
```
2. **Animate to progress**:
```javascript
circle.animate(0.75, {
duration: 1500,
easing: 'easeOut'
}, function() {
console.log('Animation complete');
});
```
3. **Update dynamically**:
```javascript
circle.setText('Loading...');
circle.pause();
circle.resume();
```
4. **Cleanup when done**:
```javascript
circle.destroy();
```
```
--------------------------------
### JavaScript Initialization Example
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/docs/api/general.md
Example of initializing a Circle progress bar with custom options for color, stroke width, trail width, and text display.
```javascript
var circle = new ProgressBar.Circle('#example-percent-container', {
color: '#FCB03C',
strokeWidth: 3,
trailWidth: 1,
text: {
value: '0'
}
});
```
--------------------------------
### Install Testing Dependencies
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/docs/contributing.md
Install global packages required for running tests, such as Mocha and Testem.
```bash
npm install -g mocha
npm install -g testem
```
--------------------------------
### Example 'from' Parameter for Animation Initialization
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/docs/api/parameters.md
Illustrates the structure of the 'from' parameter, specifying initial values for animation properties like width and color.
```javascript
{
// Start from thin gray line
width: 0.1,
color: '#eee'
}
```
--------------------------------
### Example Usage of TextOptions with ProgressBar.Circle
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/types.md
Demonstrates how to create a ProgressBar.Circle with custom text options, including value, class name, and inline styles.
```javascript
var textOptions = {
value: '0%',
className: 'custom-label',
style: {
color: '#ff0000',
fontSize: '24px',
position: 'absolute',
left: '50%',
top: '50%',
transform: {
prefix: true,
value: 'translate(-50%, -50%)'
}
}
};
var circle = new ProgressBar.Circle('#container', {
text: textOptions
});
```
--------------------------------
### Complete Progressbar.js Circle Configuration
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/configuration.md
A comprehensive example demonstrating how to initialize and configure a Circle progress bar with various styling, text, and animation options.
```javascript
var circle = new ProgressBar.Circle('#container', {
// Animation defaults
duration: 1200,
delay: 100,
easing: 'easeInOut',
// Style
color: '#3498db',
strokeWidth: 4,
trailColor: '#ecf0f1',
trailWidth: 2,
fill: null,
// SVG styling
svgStyle: {
display: 'block',
width: '100%'
},
// Text label
text: {
value: '0%',
className: 'progress-label',
autoStyleContainer: true,
style: {
color: '#3498db',
position: 'absolute',
left: '50%',
top: '50%',
padding: 0,
margin: 0,
transform: {
prefix: true,
value: 'translate(-50%, -50%)'
}
}
},
// Custom animation
from: { rotation: 0 },
to: { rotation: 360 },
step: function(state, circle, attachment) {
// Called every frame
circle.path.style.transform = 'rotate(' + state.rotation + 'deg)';
},
// Debugging
warnings: true
});
```
--------------------------------
### Example of Destroying and Recreating a Progress Bar
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/api-reference/shape.md
Demonstrates the typical lifecycle of a progress bar instance, including its destruction and subsequent recreation.
```javascript
var progressBar = new ProgressBar.Circle('#container');
progressBar.animate(0.5);
// Later, when done...
progressBar.destroy();
// progressBar.animate() will now throw an error
// Create a new one if needed
progressBar = new ProgressBar.Circle('#container');
```
--------------------------------
### Example Usage of ShapeOptions
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/types.md
Demonstrates initializing a ProgressBar.Circle with custom ShapeOptions. Shows setting color, stroke width, trail color, duration, easing, and text label configuration.
```javascript
var options = {
color: '#3498db',
strokeWidth: 3,
trailColor: '#ecf0f1',
duration: 1500,
easing: 'easeInOut',
text: {
value: 'Loading...'
}
};
var circle = new ProgressBar.Circle('#container', options);
```
--------------------------------
### Example 'to' Parameter for Animation Finalization
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/docs/api/parameters.md
Demonstrates the structure of the 'to' parameter, defining the final values for animation properties such as width and color.
```javascript
{
// Finish to thick black line
width: 1,
color: '#000'
}
```
--------------------------------
### Instantiate Square Progress Bar
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/api-reference/square.md
Creates a new square progress bar in the specified container. This is a basic example of instantiation.
```javascript
var square = new ProgressBar.Square('#container', {
strokeWidth: 2,
color: '#3a3a3a'
});
```
--------------------------------
### Apply Vendor Prefixes to CSS Styles
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/types.md
Example demonstrating how to apply vendor-prefixed CSS styles for transform and opacity properties. Ensure 'prefix: true' is set for styles requiring cross-browser compatibility.
```javascript
var circle = new ProgressBar.Circle('#container', {
text: {
value: '50%',
style: {
transform: {
prefix: true,
value: 'translate(-50%, -50%)'
},
opacity: {
prefix: true,
value: '0.8'
}
}
}
});
```
--------------------------------
### Basic Circle Initialization
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/api-reference/shape.md
Shows a basic example of initializing a Circle progress bar. This constructor is typically used via subclasses like Line, Circle, or SemiCircle.
```javascript
// Typically use subclasses instead:
var circle = new ProgressBar.Circle('#container', {
color: '#3a3a3a',
strokeWidth: 2
});
```
--------------------------------
### Full Circle Progress Bar Example
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/api-reference/circle.md
Demonstrates a fully configured circular progress bar with text, custom animation duration, and easing. It also shows how to update text during animation.
```javascript
var circle = new ProgressBar.Circle('#container', {
color: '#FCB03C',
strokeWidth: 3,
trailColor: '#eee',
trailWidth: 1,
text: {
value: '0%',
className: 'progressbar__label'
},
duration: 1200,
easing: 'easeInOut'
});
circle.animate(0.75, function() {
console.log('75% complete');
});
// Update text during animation
circle.setText('Loading...');
```
--------------------------------
### Example Usage of AnimationOptions
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/types.md
Demonstrates how to use the AnimationOptions object with a `.animate()` call. Shows setting duration, easing, custom start/end values, and a step function for updating the shape's path.
```javascript
var options = {
duration: 2000,
easing: 'easeOut',
from: { color: '#000' },
to: { color: '#f00' },
step: function(state, shape) {
shape.path.setAttribute('stroke', state.color);
}
};
circle.animate(0.75, options, function() {
console.log('Done');
});
```
--------------------------------
### Fix Non-Existent Container Errors by Waiting for DOM
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/errors.md
This example shows how to fix 'Container does not exist' errors by waiting for the DOM to be fully loaded before initializing the ProgressBar.
```javascript
// Wait for DOM to be ready
document.addEventListener('DOMContentLoaded', function() {
var circle = new ProgressBar.Circle('#container');
});
// Or verify element exists
var element = document.querySelector('#container');
if (element) {
var circle = new ProgressBar.Circle(element);
} else {
console.error('Container element not found');
}
```
--------------------------------
### Example SVG Path
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/api-reference/path.md
An example of an SVG path element with required attributes for use with Path animator. Ensure fill-opacity is 0 and stroke attributes are set.
```html
```
--------------------------------
### Example Usage of PathOptions
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/types.md
Demonstrates how to create a PathOptions object for customizing a ProgressBar.Path animation, including setting duration, easing, start/end colors, and a step function to update the path's stroke color.
```javascript
var pathOptions = {
duration: 1500,
easing: 'easeOut',
from: { color: '#000' },
to: { color: '#f00' },
step: function(state, path, attachment) {
path.path.setAttribute('stroke', state.color);
}
};
var path = new ProgressBar.Path(svgPath, pathOptions);
```
--------------------------------
### Create and Animate a Path
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/api-reference/path.md
Instantiate a Path animator with an SVG path element and its options, then start the animation. Ensure the SVG element is already in the DOM.
```javascript
var svgPath = document.getElementById('my-path');
var path = new ProgressBar.Path(svgPath, {
duration: 800,
easing: 'easeOut'
});
path.animate(0.5);
```
--------------------------------
### PathOptions Configuration Object
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/types.md
Defines the configuration options for the Path constructor, including delay, duration, easing, starting and ending values, and step callbacks.
```typescript
{
delay?: number; // Default: 0
duration?: number; // Default: 800
easing?: string; // Default: 'linear'
from?: object; // Default: {}
to?: object; // Default: {}
step?: function; // Default: function() {}
attachment?: object; // Default: undefined
}
```
--------------------------------
### Full SemiCircle Example with Animation and Text
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/api-reference/semicircle.md
Demonstrates a fully configured semi-circle progress bar with custom stroke, trail, text styling, and animation duration. The animation progresses to 0.6 and logs a message upon completion.
```javascript
var semicircle = new ProgressBar.SemiCircle('#container', {
strokeWidth: 3,
color: '#FCB03C',
trailColor: '#f4f4f4',
trailWidth: 1,
text: {
value: 'Loading',
style: {
color: '#333',
position: 'absolute',
left: '50%',
top: '50%',
padding: 0,
margin: 0,
transform: {
prefix: true,
value: 'translate(-50%, -50%)'
}
},
alignToBottom: false
},
duration: 1000
});
semicircle.animate(0.6, function() {
console.log('Animation complete');
});
```
--------------------------------
### Embedded SVG Example
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/api-reference/path.md
Demonstrates how to embed an SVG file using an object tag. This method requires loading the SVG content to access its elements.
```html
```
--------------------------------
### Custom Step Function for Animation Updates
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/docs/api/parameters.md
Provides an example of a custom 'step' function that updates the stroke width and color of the path, and displays the current progress percentage.
```javascript
function(state, shape, attachment) {
shape.path.setAttribute('stroke-width', state.width);
shape.path.setAttribute('stroke', state.color);
attachment.text.innerHTML = shape.value() * 100;
}
```
--------------------------------
### Horizontal and Vertical Line Progress Bars
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/api-reference/line.md
Demonstrates creating both horizontal and vertical line progress bars. The 'vertical' option controls the orientation. Includes an example of animating the progress bar.
```javascript
// Horizontal line
var progressBar = new ProgressBar.Line('#container', {
strokeWidth: 3,
color: '#3a3a3a',
trailColor: '#f4f4f4',
trailWidth: 1,
duration: 1000
});
// Vertical line
var verticalBar = new ProgressBar.Line('#vertical-container', {
vertical: true,
strokeWidth: 2,
color: '#0066cc'
});
progressBar.animate(0.5, function() {
console.log('Animation complete');
});
```
--------------------------------
### CSS for Line Progress Bar Container
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/api-reference/line.md
Provides CSS examples for sizing the container element to match the aspect ratio of the SVG canvas for both horizontal and vertical line progress bars.
```css
#container {
width: 100%;
height: 3px;
}
```
```css
#vertical-container {
width: 50px;
height: 300px;
}
```
--------------------------------
### Container Aspect Ratio Requirement
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/api-reference/semicircle.md
CSS example showing the required 2:1 aspect ratio for the container element to ensure correct semi-circular rendering. The height must be 50% of the width.
```css
#container {
width: 300px;
height: 150px; /* Must be 50% of width */
}
```
--------------------------------
### Instantiate a Circle Progress Bar
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/api-reference/shape.md
Demonstrates how to create a Circle progress bar with custom color, stroke width, trail colors, text, animation duration, and easing function. The animate method is then called to start the animation.
```javascript
var circle = new ProgressBar.Circle('#container', {
color: '#FCB03C',
strokeWidth: 3,
trailColor: '#eee',
trailWidth: 1,
text: {
value: '0%'
},
duration: 1200,
easing: 'easeInOut'
});
circle.animate(0.5, function() {
console.log('Animation finished');
});
```
--------------------------------
### Constructor Options
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/README.md
Details all available options for initializing progress bar shapes, covering animation, styling, SVG attributes, text display, and debugging.
```APIDOC
## Constructor Options
### Description
Options used when creating a new progress bar instance to customize its behavior and appearance.
### Options Categories
#### Animation
- **duration** (number) - The total duration of the animation in milliseconds.
- **delay** (number) - The delay before the animation starts in milliseconds.
- **easing** (string or function) - The easing function to use for the animation.
- **from** (number) - The starting progress value for the animation.
- **to** (number) - The ending progress value for the animation.
- **step** (function) - A callback function executed at each animation step.
#### Style
- **color** (string) - The color of the progress bar.
- **strokeWidth** (number) - The width of the progress bar stroke.
- **trailColor** (string) - The color of the trail (background) of the progress bar.
- **trailWidth** (number) - The width of the trail.
- **fill** (string) - The fill color for the progress bar shape.
#### SVG
- **svgStyle** (object) - Inline SVG style attributes for the SVG element.
#### Text
- **value** (string) - Initial text to display.
- **className** (string) - CSS class for the text element.
- **autoStyleContainer** (boolean) - Automatically style the text container.
- **alignToBottom** (boolean) - Align text to the bottom of the container.
- **style** (object) - Inline styles for the text element.
#### Debug
- **warnings** (boolean) - Enable or disable console warnings.
### Examples
```javascript
// Example with animation and text options
const bar = new ProgressBar.Circle('#container', {
duration: 1000,
easing: 'easeInOut',
text: {
value: '0%'
}
});
// Example with styling options
const lineBar = new ProgressBar.Line('#container', {
color: '#FF0000',
strokeWidth: 4,
trailColor: '#EEEEEE',
trailWidth: 1
});
```
```
--------------------------------
### Configure Text Options - Simple Text
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/configuration.md
Initialize a progress bar with simple text content.
```javascript
var circle = new ProgressBar.Circle('#container', {
text: {
value: 'Loading'
}
});
```
--------------------------------
### Run Development Server
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/docs/contributing.md
Use this command to run the development server for local testing and development.
```bash
npm run dev
```
--------------------------------
### SVG Path Definition
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/api-reference/path.md
Example SVG structure for a custom path, such as a heart shape. This defines the visual element that the Path API will animate.
```html
```
--------------------------------
### Run All Tests with Testem
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/docs/contributing.md
Execute all tests using Testem, which will serve a testing page and connect to detected local browsers.
```bash
testem
```
--------------------------------
### CSS for Container Aspect Ratio
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/docs/api/general.md
Ensure your container element matches the SVG canvas aspect ratio. This example shows settings for a SemiCircle shape.
```css
#container {
width: 300px;
height: 150px;
}
```
--------------------------------
### Configure Text Options - Disable Default Styles
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/configuration.md
Initialize a progress bar with text while disabling automatic styling.
```javascript
var circle = new ProgressBar.Circle('#container', {
text: {
value: 'Progress',
style: null // No automatic styling
}
});
```
--------------------------------
### Get Current Progress Value
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/api-reference/path.md
Retrieves the current progress value of the path, ranging from 0 to 1. This is useful for checking the state of the progress bar.
```javascript
var progress = path.value();
console.log('Progress: ' + (progress * 100) + '%');
```
--------------------------------
### Basic Progress Bar Usage
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/00-START-HERE.txt
Demonstrates the creation, animation, dynamic updates, and destruction of a progress bar. Ensure the container element exists in the DOM before initializing.
```javascript
var circle = new ProgressBar.Circle('#container', {
color: '#3498db',
strokeWidth: 4,
trailColor: '#ecf0f1',
text: { value: '0%' }
});
circle.animate(0.75, {
duration: 1500,
easing: 'easeOut'
}, function() {
console.log('Animation complete');
});
circle.setText('Loading...');
circle.pause();
circle.resume();
circle.destroy();
```
--------------------------------
### Get current progress bar value
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/api-reference/shape.md
Returns the current progress value of the bar, ranging from 0 to 1. This can be used to check the progress during an animation or at any other time.
```javascript
progressBar.animate(0.5, function() {
console.log(progressBar.value()); // Logs value during animation
});
var current = progressBar.value();
if (current < 0.5) {
console.log('Less than 50%');
}
```
--------------------------------
### Square Progress Bar with Options and Animation
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/api-reference/square.md
Demonstrates creating a Square progress bar with detailed options including text, and animating it to a specific progress value. The animation callback logs a message upon completion.
```javascript
var square = new ProgressBar.Square('#container', {
strokeWidth: 3,
color: '#3498db',
trailColor: '#ecf0f1',
trailWidth: 1,
text: {
value: 'Loading'
}
});
square.animate(0.6, function() {
console.log('Animation complete');
});
```
--------------------------------
### Importing Square Shape (for reference)
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/api-reference/square.md
Illustrates how the Square shape would be imported if it were part of the build. Note that Square requires manual inclusion from source and is not in the distributed build.
```javascript
// Square requires manual inclusion from source
// It is available in src/square.js but not in the distributed build
```
--------------------------------
### Custom Animation Step Callback
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/types.md
Example of a custom step function for animations, interpolating opacity and rotation. The 'state' object provides access to interpolated values and the current offset.
```javascript
var circle = new ProgressBar.Circle('#container', {
from: { opacity: 0.5, rotation: 0 },
to: { opacity: 1.0, rotation: 360 },
step: function(state, circle, attachment) {
// state.opacity: interpolated from 0.5 to 1.0
// state.rotation: interpolated from 0 to 360
// state.offset: current stroke-dashoffset
circle.path.style.opacity = state.opacity;
circle.path.style.transform = 'rotate(' + state.rotation + 'deg)';
}
});
circle.animate(1, {duration: 2000});
```
--------------------------------
### Color Transition During Progress
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/api-reference/path.md
Animates an SVG path while transitioning its stroke color from a starting color to an ending color. The 'step' function updates the path's stroke attribute.
```javascript
var path = new ProgressBar.Path(svgPath, {
from: { color: '#3498db' },
to: { color: '#e74c3c' },
step: function(state, path) {
path.path.setAttribute('stroke', state.color);
}
});
path.animate(1, {duration: 3000});
```
--------------------------------
### Create a Major Release
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/docs/contributing.md
Run the release task with a 'major' version bump to create a new major release.
```bash
grunt release:major
```
--------------------------------
### Circle Progress Bar with Custom Colors and Step Animation
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/api-reference/circle.md
Demonstrates how to use custom colors for the progress bar and its trail, and how to animate color changes during the progress using the `step` function.
```javascript
var circle = new ProgressBar.Circle('#container', {
color: '#0066cc',
trailColor: '#e0e0e0',
trailWidth: 2,
strokeWidth: 4,
from: { color: '#0066cc' },
to: { color: '#00cc00' },
step: function(state, circle) {
circle.path.setAttribute('stroke', state.color);
}
});
```
--------------------------------
### Properly Handling ProgressBar Destruction and Re-creation
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/errors.md
Illustrates the correct pattern for managing a ProgressBar instance, including its destruction and subsequent re-creation to avoid 'Object is destroyed' errors.
```javascript
var circle = new ProgressBar.Circle('#container');
// Do work...
circle.animate(0.5);
// Clean up when done
function cleanup() {
if (circle) {
circle.destroy();
circle = null; // Help garbage collection
}
}
// Don't call methods after destroy
cleanup();
// ❌ circle.animate(0.5); // Error!
// Create new instance if needed
circle = new ProgressBar.Circle('#container');
circle.animate(0.5); // ✅ OK
```
--------------------------------
### Text Options Configuration
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/api-reference/shape.md
Illustrates the structure for configuring the text label within a progress bar, including its value, CSS class, alignment, and styling.
```javascript
text: {
value: null, // Initial text content
className: 'progressbar-text', // CSS class for text element
autoStyleContainer: true, // Auto-set container position: relative
alignToBottom: true, // SemiCircle-specific: align text to bottom
style: { // CSS styles for text element
color: null, // Text color (defaults to stroke color)
position: 'absolute',
left: '50%',
top: '50%',
padding: 0,
margin: 0,
transform: {
prefix: true, // Apply browser prefixes
value: 'translate(-50%, -50%)'
}
}
}
```
--------------------------------
### Run Tests in CI Mode with Testem
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/docs/contributing.md
Run tests in continuous integration mode with Testem, executing tests on all available or detected local browsers.
```bash
testem ci
```
--------------------------------
### Ensure Square Container Aspect Ratio
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/api-reference/circle.md
CSS to ensure the container element has a square aspect ratio, which is required for proper circular rendering. Includes an example of enabling warnings for non-square containers.
```css
#container {
width: 300px;
height: 300px;
}
```
```javascript
var circle = new ProgressBar.Circle('#container', {
warnings: true
// Will warn if container is not square
});
```
--------------------------------
### Initialize and Animate a Circle Progress Bar
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/INDEX.md
This snippet demonstrates how to initialize a Circle progress bar with specific options and animate it to a progress value. Ensure the progressbar.js library is included.
```html
```
--------------------------------
### Handle IE11 strokeWidth Limit
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/errors.md
This example shows how to ensure compatibility with Internet Explorer 11 by keeping strokeWidth values at or below 6. For thicker strokes, it suggests using CSS to style the SVG container height.
```javascript
// ✅ For IE11 compatibility, keep strokeWidth <= 6
var circle = new ProgressBar.Circle('#container', {
strokeWidth: 4 // Safe value for IE11
});
// If you need thicker strokes, use CSS instead
var line = new ProgressBar.Line('#container', {
strokeWidth: 1
});
// Then style the SVG container height with CSS
document.querySelector('#container svg').style.height = '10px';
```
--------------------------------
### Initialize Custom Path with Inline SVG
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/docs/api/path.md
Instantiate a `ProgressBar.Path` by providing the SVG path element obtained from the DOM and optional animation configuration.
```javascript
var svgPath = document.getElementById('heart-path');
var path = new ProgressBar.Path(svgPath, {
duration: 300
});
```
--------------------------------
### Reset and Jump Progress
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/api-reference/path.md
Demonstrates setting the progress to zero (reset) or to a specific percentage. Useful for initializing or updating progress states instantly.
```javascript
path.set(0); // Reset to 0%
path.set(0.3); // Jump to 30%
path.set(1); // Complete
```
--------------------------------
### ProgressBar Constructors
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/INDEX.md
Instantiate different types of progress bars with specific configurations.
```APIDOC
## ProgressBar Constructors
### Description
Use these constructors to create various progress bar shapes. Each constructor takes a container element and an options object.
### Constructors
- **`new ProgressBar.Circle(container, options)`**
- **Canvas**: 100x100
- **Aspect Ratio**: 1:1
- **Usage**: Circular progress (0-360°)
- **`new ProgressBar.Line(container, options)`**
- **Canvas**: 100x{strokeWidth}
- **Aspect Ratio**: Flexible
- **Usage**: Linear progress (horizontal/vertical)
- **`new ProgressBar.SemiCircle(container, options)`**
- **Canvas**: 100x50
- **Aspect Ratio**: 2:1
- **Usage**: Semi-circular progress (0-180°)
- **`new ProgressBar.Path(element, options)`**
- **Canvas**: Custom
- **Aspect Ratio**: Custom
- **Usage**: Custom SVG path animation
```
--------------------------------
### Run Tests with Specific Reporter and Browser
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/docs/contributing.md
Execute tests using Testem in CI mode, specifying the 'dot' reporter and targeting the Chrome browser.
```bash
testem ci -R dot -l chrome
```
--------------------------------
### Incorrect Aspect Ratio Warning Example
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/errors.md
This snippet demonstrates how a warning is logged when the container's aspect ratio does not match the shape's expected ratio. It also shows how to fix the container's aspect ratio to resolve the warning.
```javascript
// ❌ This logs a warning
var circle = new ProgressBar.Circle('#container', {
warnings: true
});
// Container is 300x200 (1.5:1) but Circle expects 1:1
// ✅ Fix the container aspect ratio
document.querySelector('#container').style.width = '300px';
document.querySelector('#container').style.height = '300px';
```
--------------------------------
### Documentation Directory Structure
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/MANIFEST.md
Overview of the generated documentation files and their organization.
```text
output/
├── README.md # This directory overview
├── MANIFEST.md # This file - generation details
├── INDEX.md # Main reference and navigation
├── configuration.md # All options and parameters
├── types.md # Type definitions
├── errors.md # Error reference
└── api-reference/
├── shape.md # Base Shape class
├── circle.md # Circle progress bar
├── line.md # Line progress bar
├── semicircle.md # SemiCircle progress bar
├── path.md # Path animator (custom SVG)
└── square.md # Square progress bar (deprecated)
```
--------------------------------
### Apply Easing Functions to Progress Bar Animation
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/configuration.md
Demonstrates how to set an initial easing function for a progress bar and apply a different easing function during the animation. Supports various preset and extended easing options.
```javascript
var circle = new ProgressBar.Circle('#container', {
easing: 'easeOutElastic'
});
circle.animate(1, {
easing: 'easeOutBounce'
});
```
--------------------------------
### Common Methods
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/INDEX.md
Control and interact with progress bar animations and state using these shared methods.
```APIDOC
## Common Methods
### Description
These methods are available on all progress bar shapes for controlling animations, setting values, and managing the progress bar's lifecycle.
### Methods
- **`.animate(progress, [options], [callback])`**
- **Parameters**: `progress` (number), `options` (object, optional), `callback` (function, optional)
- **Returns**: void
- **Description**: Animate the progress bar to a specified value.
- **`.set(progress)`**
- **Parameters**: `progress` (number)
- **Returns**: void
- **Description**: Set the progress bar's value instantly without animation.
- **`.value()`**
- **Parameters**: None
- **Returns**: number
- **Description**: Get the current progress value (between 0 and 1).
- **`.stop()`**
- **Parameters**: None
- **Returns**: void
- **Description**: Stop the current animation.
- **`.pause()`**
- **Parameters**: None
- **Returns**: void
- **Description**: Pause the current animation.
- **`.resume()`**
- **Parameters**: None
- **Returns**: void
- **Description**: Resume a paused animation.
- **`.setText(text)`**
- **Parameters**: `text` (string | HTMLElement)
- **Returns**: void
- **Description**: Update or create a text label for the progress bar.
- **`.destroy()`**
- **Parameters**: None
- **Returns**: void
- **Description**: Remove the progress bar from the DOM and clean up resources.
```
--------------------------------
### Core Methods
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/00-START-HERE.txt
Control and query the state of the progress bar using these core methods.
```APIDOC
## Core Methods
### Description
Control and query the state of the progress bar using these core methods.
### Methods
- **.animate(progress, [options], [callback])**
- **Description**: Animates the progress bar to a specified progress value.
- **Parameters**:
- **progress** (number) - The target progress value (0-1).
- **options** (object, optional) - Animation options like duration and easing.
- **callback** (function, optional) - A function to call when the animation is complete.
- **Return**: void
- **.set(progress)**
- **Description**: Sets the progress bar to a specific progress value without animation.
- **Parameters**:
- **progress** (number) - The target progress value (0-1).
- **Return**: void
- **.stop()**
- **Description**: Stops the current animation.
- **Return**: void
- **.pause()**
- **Description**: Pauses the progress bar animation.
- **Return**: void
- **.resume()**
- **Description**: Resumes a paused progress bar animation.
- **Return**: void
- **.value()**
- **Description**: Gets the current progress value of the bar.
- **Return**: number (0-1)
- **.setText(text)**
- **Description**: Sets the text displayed on the progress bar.
- **Parameters**:
- **text** (string) - The text to display.
- **Return**: void
- **.destroy()**
- **Description**: Removes the progress bar from the DOM and cleans up resources.
- **Return**: void
```
--------------------------------
### Progressbar.js Common Options
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/INDEX.md
Provides a comprehensive list of common options available when initializing a ProgressBar.Circle. These options control animation, styling, text labels, and custom animations.
```javascript
new ProgressBar.Circle('#container', {
// Animation
duration: 800,
delay: 0,
easing: 'linear',
// Style
color: '#555',
strokeWidth: 1.0,
trailColor: '#eee',
trailWidth: 1,
fill: null,
// SVG styling
svgStyle: { display: 'block', width: '100%' },
// Text label
text: {
value: 'Loading',
className: 'progress-label',
style: { /* CSS styles */ }
},
// Custom animation
from: {},
to: {},
step: function(state, shape) {},
// Debugging
warnings: false
});
```
--------------------------------
### Basic Circle Progress Bar
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/INDEX.md
Demonstrates how to create a basic circular progress bar, animate it to a specific value, and retrieve its current value.
```javascript
var circle = new ProgressBar.Circle('#container', {
color: '#3498db',
strokeWidth: 4,
trailColor: '#ecf0f1'
});
circle.animate(0.75, {
duration: 1000,
easing: 'easeOut'
}, function() {
console.log('Done!');
});
console.log(circle.value()); // Logs value between 0 and 1
```
--------------------------------
### Safe Initialization Pattern for Progress Bar
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/errors.md
This pattern ensures a progress bar is safely initialized by verifying the container exists, using the 'new' keyword correctly, and checking for errors during path creation. It returns the progress bar instance or null if initialization fails.
```javascript
function initProgressBar() {
try {
// 1. Verify container exists
var container = document.querySelector('#container');
if (!container) {
throw new Error('Container #container not found');
}
// 2. Create with new keyword
var circle = new ProgressBar.Circle(container, {
color: '#3498db',
strokeWidth: 3
});
// 3. Check for errors before use
if (!circle.path) {
throw new Error('Failed to create progress bar path');
}
return circle;
} catch (err) {
console.error('Failed to initialize progress bar:', err.message);
return null;
}
}
var progressBar = initProgressBar();
if (progressBar) {
progressBar.animate(0.5);
}
```
--------------------------------
### Path Constructor with Custom Animation Options
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/configuration.md
Configure a ProgressBar.Path with custom animation parameters like 'duration', 'easing', 'from', 'to', and 'step'. The 'step' function is invoked on each animation frame to update the path's style.
```javascript
var path = new ProgressBar.Path(svgPathElement, {
duration: 1500,
easing: 'easeOut',
from: { opacity: 0 },
to: { opacity: 1 },
step: function(state, path, attachment) {
path.path.style.opacity = state.opacity;
}
});
```
--------------------------------
### Simple Animation with Callback
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/api-reference/path.md
Performs a simple animation to a given progress value and executes a callback upon completion. Useful for basic progress indication.
```javascript
// Simple animation with callback
path.animate(0.5, function() {
console.log('Done');
});
```
--------------------------------
### Initialize ProgressBar with Custom Animation Options
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/docs/api/parameters.md
Define custom animation properties like color and the step function during ProgressBar initialization. This sets the default animation behavior.
```javascript
var bar = new ProgressBar.Line('#container', {
from: { color: '#000 '},
to: { color: '#888 '},
step: function(state, bar, attachment) {
bar.path.setAttribute('stroke', state.color);
}
});
```
--------------------------------
### ProgressBar Construction
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/00-START-HERE.txt
Instantiate different types of progress bars by providing a container element and options.
```APIDOC
## ProgressBar Construction
### Description
Instantiate different types of progress bars by providing a container element and options.
### Constructors
- **new ProgressBar.Circle(container, options)**
- **new ProgressBar.Line(container, options)**
- **new ProgressBar.SemiCircle(container, options)**
- **new ProgressBar.Path(svgPathElement, options)**
```
--------------------------------
### Reset and set progress bar values
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/api-reference/shape.md
Demonstrates resetting the progress bar to 0% and setting it to specific values like 25% and 100%.
```javascript
progressBar.set(0); // Reset to 0%
progressBar.set(0.25); // Set to 25%
progressBar.set(1); // Set to 100%
```
--------------------------------
### .resume()
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/docs/api/path.md
Resumes a suspended animation from where it was paused.
```APIDOC
## .resume()
### Description
Resumes animation from a previously paused position.
```
--------------------------------
### Enable Container Aspect Ratio Warnings
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/api-reference/semicircle.md
Configures the SemiCircle progress bar to issue warnings if the container element does not adhere to the required 2:1 aspect ratio.
```javascript
var semicircle = new ProgressBar.SemiCircle('#container', {
warnings: true
// Will warn if container is not 2:1 aspect ratio
});
```
--------------------------------
### Handle Non-Existent Container Errors
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/errors.md
This snippet demonstrates how to avoid the 'Container does not exist' error by ensuring the specified DOM element is available when creating a ProgressBar instance.
```javascript
// ❌ This throws the error if #nonexistent doesn't exist
var circle = new ProgressBar.Circle('#nonexistent', {});
// ✅ Valid element
var circle = new ProgressBar.Circle('#container', {});
```
--------------------------------
### Including ProgressBar.js via Browser Global Script
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/_autodocs/INDEX.md
Include the library using a script tag in HTML for direct use in the browser.
```html
```
--------------------------------
### new ProgressBar.Path(path, [*options*])
Source: https://github.com/kimmobrunfeldt/progressbar.js/blob/master/docs/api/path.md
Constructor for creating a custom shaped progress bar using an SVG path. It accepts an SVG path element or selector and optional animation configurations.
```APIDOC
## new ProgressBar.Path(path, [*options*])
### Description
Custom shaped progress bar. You can create arbitrary shaped progress bars by passing a SVG path created with e.g. Adobe Illustrator. It's on caller's responsibility to append SVG to DOM.
### Parameters
* `path` [SVG Path](https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Paths) object or plain selector string. For example `$('svg > path:first-child')[0]`.
* `options` Animation options.
```javascript
{
// Duration for animation in milliseconds
// Default: 800
duration: 1200,
// Delay for animation in milliseconds
// Default: 0
delay: 100,
// Easing for animation. See #easing section.
// Default: 'linear'
easing: 'easeIn',
// Attachment which can be any object
// you need to modify within the step function.
// Passed as a parameter to step function.
// Default: undefined
attachment: document.querySelector('#container > svg'),
// See #custom-animations section
from: { color: '#eee' },
to: { color: '#000' },
step: function(state, path, attachment) {
// Do any modifications to attachment and/or path attributes
}
}
```
### Example
Assuming there was SVG object with heart shaped path in HTML
```html
```
Initialization would be this easy
```javascript
var svgPath = document.getElementById('heart-path');
var path = new ProgressBar.Path(svgPath, {
duration: 300
});
```
**Working with embedded SVG**
If the SVG was not inline in the HTML but instead in, say, an `