SpinOnSubmitJS

SpinOnSubmitJS is a lightweight JavaScript library that enhances form submission buttons with loading indicators, success/error states, and animations. It provides an intuitive way to handle asynchronous actions while providing visual feedback to users.

Installation

Install via npm:

npm install spinonsubmitjs

Features

SpinOnSubmitJS includes:

• Loading spinner with customizable appearance
• Success and error states with icons
• Multiple animation options (checkmark, pulse, shake, fade)
• Custom loading text/HTML support
• Automatic form reset capability
• Flexible positioning and styling
• CSS variables for easy theming
• ARIA attributes for accessibility

Usage

1. Import the library:

import { createSpinnerButton } from 'spinonsubmitjs';

2. Create a button and form in your HTML:

<form id="myForm">
   <input type="text" name="firstName" />
   <input type="text" name="lastName" />
   <button id="submitBtn">Submit</button>
</form>

3. Initialize the button:

createSpinnerButton(
   'submitBtn',
   'myForm',
   async (data) => {
       // Your submission logic here
       await submitData(data);
   },
   (error) => {
       console.error('Submission failed:', error);
   },
   {
       spinnerColor: '#3498db',
       position: 'right',
       hideLabelWhileLoading: true,
       showSuccessState: true,
       successAnimation: 'checkmark',
       showErrorState: true,
       errorAnimation: 'shake',
       loadingText: 'Submitting...',
       resetForm: true,
       onLoadingStart: () => console.log('Loading started'),
       onLoadingFinished: () => console.log('Loading finished')
   }
);

Configuration Options

The spinnerOptions object accepts the following properties:

| Option | Type | Default | Description | |--------|------|---------|-------------| | spinnerColor | string | '' | Color of the spinner | | position | string | 'left' | Position of spinner ('left' or 'right') | | hideLabelWhileLoading | boolean | true | Hide button text during loading | | showLabel | boolean | true | Show button label | | loadingText | string | undefined | Text to show during loading | | loadingHtml | string | undefined | HTML to show during loading | | showSuccessState | boolean | false | Show success icon after completion | | showErrorState | boolean | false | Show error icon on failure | | successAnimation | string | 'checkmark' | Success animation type ('checkmark' or 'pulse') | | errorAnimation | string | 'shake' | Error animation type ('shake' or 'fade') | | resetForm | boolean | false | Reset form after error | | onLoadingStart | function | undefined | Callback when loading starts | | onLoadingFinished | function | undefined | Callback when loading ends |

Styling

The library includes CSS variables for easy customization:

:root {
   --sos-spinner-size: 20px;
   --sos-spinner-border-color-light: #f3f3f3;
   --sos-spinner-border-top-color: #3498db;
   --sos-spinner-margin-right: 5px;
   --sos-icon-size: 20px;
   --sos-icon-stroke: 3px;
   --color-success: green;
   --color-danger: red;
}

Events

The button emits a 'loadingFinished' event when the submission process completes:

button.addEventListener('loadingFinished', (event) => {
   const hasError = event.detail.error;
   console.log('Loading finished with error:', hasError);
});

Examples

Here's a complete example showing various features:

createSpinnerButton(
   'submitBtn',
   'myForm',
   (data) => {
       return new Promise((resolve, reject) => {
           setTimeout(() => {
               if (data.firstName && data.lastName) {
                   resolve();
               } else {
                   reject('All fields must be filled!');
               }
           }, 2000);
       });
   },
   (error) => {
       console.error('Error:', error);
   },
   {
       spinnerColor: '#3498db',
       position: 'right',
       hideLabelWhileLoading: true,
       showSuccessState: true,
       successAnimation: 'checkmark',
       loadingText: 'Processing...',
       onLoadingFinished: () => {
           console.log('Form submission completed');
       }
   }
);

License

SpinOnSubmitJS is released under the MIT license. You are free to use, modify, and distribute this software for any purpose, commercial or non-commercial, with proper attribution.