HoldCircleJS

Introduction

HoldCircleJS is a lightweight, vanilla JavaScript library designed to create interactive radial progress indicators. Inspired by the bold and raw aesthetic of Neobrutalism, HoldCircleJS offers a unique and engaging way to display progress for user actions like click-and-hold. The library is customizable and easy to integrate into any modern web project.

Installation

To install HoldCircleJS in your project, use npm:

npm install holdcirclejs

Usage

After installation, include HoldCircleJS in your project:

import HoldCircle from 'holdcirclejs';

Initialize HoldCircleJS with desired options:

        const holdCircle = new HoldCircle({
          startDelay: 500, // Delay before starting the fill (milliseconds)
          fillTime: 2000, // Time to complete the fill (milliseconds)
          strokeColor: '#ff0000', // Color of the stroke
          fillColor: 'rgba(255, 0, 0, 0.5)', // Fill color inside the circle (optional)
          strokeWidth: 8, // Width of the stroke (pixels)
          radius: 40, // Radius of the circle (pixels)
          global: false, // True for entire page, false for elements with data-holdcircle attribute
          elClass: 'custom-class', // Class name to target specific elements (optional)
          ignoreClass: ['ignore-me'], // Array of class names to ignore (optional)
          text: 'Loading', // Text to display inside the circle (optional)
          textClass: 'text-style', // Class name for text styling (optional)
          easingFunction: (t) => t * (2 - t), // Custom easing function (optional)
          callback: function() { console.log('Completed!'); } // Callback function to execute when the fill is complete
      });      
            

Configuration Options

HoldCircleJS can be customized with the following options:

• startDelay (number): Time in milliseconds before starting the fill (default: 500)
• fillTime (number): Time in milliseconds to complete the fill (default: 2000)
• strokeColor (string): HEX color of the stroke (default: '#00ff00')
• fillColor (string): Fill color inside the circle (optional)
• strokeWidth (number): Width of the stroke in pixels (default: 5)
• radius (number): Radius of the circle in pixels (default: 30)
• global (boolean): True for entire page, false for elements with data-holdcircle attribute (default: false)
• elClass (string): Class name to target specific elements (optional)
• ignoreClass (array of strings): Array of class names to ignore (optional)
• text (string): Text to display inside the circle (optional)
• textClass (string): Class name for text styling (optional)
• easingFunction (function): Custom easing function for the animation (optional)
• callback (function): Function to be called when the progress completes

Callback Function

The callback function is executed when the user completes the hold action (i.e., when the radial progress completes). You can define any custom logic in this callback:

const holdCircle = new HoldCircle({
    // ... other options ...
    callback: function() {
        // Custom logic here
        alert('Hold action completed!');
    }
});
            

Examples

Below are three different button examples using HoldCircleJS:

<button class="nb-button green" data-holdcircle data-holdcircle-color="#40d39c" data-holdcircle-fill="rgba(0,0,0,0)">Hold me</button>

<button class="nb-button sky-blue" data-holdcircle data-holdcircle-color="#0077b6" data-holdcircle-fill="rgba(0,119,182,0.25)">Hold me</button>

<button class="nb-button pale-red" data-holdcircle data-holdcircle-color="#ff5733">Hold me</button>