holdcirclejs v1.0.3

HoldCircleJS

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.

Features

• Customizable start delay and fill time
• Adjustable stroke color and width
• Configurable radius size
• Callback function support
• Option to activate on specific elements or the entire page
• Data attributes for element-specific customization

Installation

Install HoldCircleJS using npm:

npm install holdcirclejs

Usage

Import HoldCircleJS and initialize it with desired options:

import HoldCircle from 'holdcirclejs';

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
});

Advanced example

    <!-- Button 1 - Alert callback -->
    <button class="nb-button green rounded hold-circle-alert" data-holdcircle data-holdcircle-color="#40d39c" data-holdcircle-fill="rgba(0,0,0,0)">Hold me to see what I do</button>
    
    <!-- Button 2: Modal callback -->
    <button class="nb-button sky-blue rounded hold-circle-modal" data-holdcircle data-holdcircle-color="#0077b6" data-holdcircle-fill="rgba(0,119,182,0.25)">Hold me to see what I do</button>

    <!-- Example 3: GLOBAL with custom color -->
    <button class="nb-button pale-red rounded" data-holdcircle data-holdcircle-color="#ff5733">Hold me</button>

    <script>
        const addToClipboard = () => {
            navigator.clipboard.writeText("I love HoldCircleJS! :)");
        }

        const openModal = () => {
            addToClipboard();
            document.querySelector('#modal').checked = true;
        }

        const showAlert = () => {
            document.querySelector('.alert.fixed-bottom').classList.add('show');
            setTimeout(() => {
                document.querySelector('.alert.fixed-bottom').classList.remove('show');
            }, 3000)
        }

        // HoldCircle with a callback
        const holdCircleModal = new HoldCircle({
            startDelay: 500,
            fillTime: 750,
            strokeColor: '#ff0000',
            fillColor: 'rgba(255, 0, 0, 0.1)',
            strokeWidth: 6,
            radius: 32,
            elClass: "hold-circle-modal",
            global: false, 
            easingFunction: (t) => t * (2 - t), // Example ease-out quadratic
            callback: openModal
        });

        // HoldCircle with another callback
        const holdCircleAlert = new HoldCircle({
            startDelay: 500,
            fillTime: 750,
            strokeColor: '#ff0000',
            fillColor: 'rgba(255, 0, 0, 0.1)',
            strokeWidth: 6,
            radius: 32,
            elClass: "hold-circle-alert",
            global: false, 
            easingFunction: (t) => t * (2 - t), // Example ease-out quadratic
            callback: showAlert
        });

        // Global HoldCircle with ignores
        const holdCircleGlobal = new HoldCircle({
            startDelay: 500,
            fillTime: 750,
            strokeColor: '#fdfd96',
            fillColor: '#ffc5c8',
            strokeWidth: 10,
            radius: 50,
            global: true, 
            ignoreClass: ["hold-circle-alert", "hold-circle-modal"], // Make sure to ignore the classes attached to the other HoldCircle instances to avoid multiple HoldCircle instances appear at once
            text: ":)",
            easingFunction: (t) => t * (2 - t), // Example ease-out quadratic
        });
    </script>

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') strokeWidth (number): Width of the stroke in pixels (default: 5) radius (number): Radius of the circle in pixels (default: 30) callback (function): Function to be called when the progress completes

Element-Specific Customization

Use data-holdcircle-color and data-holdcircle-fill attributes on HTML elements to customize the stroke and fill colors:

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

License

HoldCircleJS is MIT licensed.