About the Library

SpinOnSubmitJS is a lightweight JavaScript library designed to enhance user experience during form submissions and other asynchronous actions triggered by button clicks. It provides a simple yet effective way to visually indicate a loading state by adding a spinner to the button and disabling it to prevent multiple submissions.

This library is perfect for developers who want to improve the interactivity and user feedback of their web applications with minimal code and easy integration.

Installation

SpinOnSubmitJS is available as an NPM package. To install it, run: 

npm install spinonsubmitjs

Usage

Integrate SpinOnSubmitJS into your project by following these steps:

  1. Include SpinOnSubmitJS in your project. If you installed via NPM, import it in your JavaScript file: 
    import { createSpinnerButton } from 'spinonsubmitjs';
  2. Identify the button and form elements in your HTML by their IDs.
  3. Call the createSpinnerButton function in your JavaScript code, typically after the DOM is loaded. Pass the button ID, form ID, an onSubmit function (that returns a Promise), and optionally an onError function, and a spinnerOptions object.

The createSpinnerButton function accepts the following parameters: 



createSpinnerButton(
    buttonId: string,
    formId: string,
    onSubmit: function,
    onError?: function,
    spinnerOptions: object
)

Spinner Options

Customize the button's spinner and behavior using the spinnerOptions object:

  • spinnerColor: Sets the color of the spinner.
  • position: Spinner position: 'left' or 'right'.
  • hideLabelWhileLoading: Hide label during loading? (boolean)
  • showLabel: Show label initially? (boolean)
  • loadingText: Text to show during loading.
  • loadingHtml: HTML to show during loading.
  • onLoadingStart: Callback on loading start.
  • onLoadingFinished: Callback on loading finish.
  • showSuccessState: Show success state? (boolean)
  • showErrorState: Show error state? (boolean)
  • successAnimation: Animation for success: 'checkmark', 'pulse', or 'none'.
  • errorAnimation: Animation for error: 'shake', 'fade' or 'none'.
  • resetForm: Function to reset form.

Examples

Example 1: Default with Enhanced Success/Error


createSpinnerButton(
    'defaultSubmitBtn',
    'exampleForm',
    (data) => simulateAction(data.firstName !== '' && data.lastName !== ''),
    handleError,
    {
        successAnimation: 'checkmark',
        errorAnimation: 'shake',
        resetForm: resetExampleForm
    }
);

Example 2: Spinner-Only (Less Common)


createSpinnerButton(
    'spinnerOnlyBtn',
    'exampleForm',
    () => simulateAction(true),
    handleError,
    {
        showLabel: false,
        successAnimation: 'none',
        errorAnimation: 'none',
        resetForm: resetExampleForm
    }
);

Example 3: Label Always Shown


createSpinnerButton(
  'labelAlwaysShownBtn',
  'exampleForm',
  () => simulateAction(true),
  handleError,
  {
      position: 'right',
      hideLabelWhileLoading: false,
      successAnimation: 'pulse',
      errorAnimation: 'fade',
      resetForm: resetExampleForm
  }
);

Example 4: Loading Text


createSpinnerButton(
  'loadingTextBtn',
  'exampleForm',
  () => simulateAction(true),
  handleError,
  {
      loadingText: 'Processing...',
      successAnimation: 'checkmark',
      errorAnimation: 'shake',
      resetForm: resetExampleForm
  }
);

Example 5: Loading HTML


createSpinnerButton(
  'loadingHtmlBtn',
  'exampleForm',
  () => simulateAction(true),
  handleError,
  {
      loadingHtml: ' Loading...',
      successAnimation: 'checkmark',
      errorAnimation: 'shake',
      resetForm: resetExampleForm
  }
);

Example 6: Success State (Explicit)


createSpinnerButton(
  'successStateBtn',
  'exampleForm',
  () => simulateAction(true),
  handleError,
  {
      showSuccessState: true,
      successAnimation: 'checkmark',
      resetForm: resetExampleForm
  }
);

Example 7: Error State (Explicit)


createSpinnerButton(
  'errorStateBtn',
  'exampleForm',
  () => simulateAction(false),
  handleError,
  {
      showErrorState: true,
      errorAnimation: 'shake',
      resetForm: resetExampleForm
  }
);

Example 8: Callbacks


createSpinnerButton(
  'callbackBtn',
  'exampleForm',
  () => simulateAction(true),
  handleError,
  {
      onLoadingStart: () => console.log('Loading started!'),
      onLoadingFinished: (event) => console.log('Loading finished! Error:', event.detail.error),
      resetForm: resetExampleForm
  }
);

Example 9: Contact Form


createSpinnerButton(
  'contactSubmitBtn',
  'contactForm',
  (data) => simulateAction(data.email !== '' && data.message !== ''),
  handleError,
  {
      successAnimation: 'pulse',
      errorAnimation: 'fade',
      resetForm: resetContactForm
  }
);

CSS Customization

SpinOnSubmitJS is styled using CSS variables, allowing for easy and flexible customization to match your project's design. Redefine these variables in your CSS to alter the appearance of the spinner and icons globally or specifically.

The following CSS variables are available:

  • --sos-spinner-size: Size (width and height) of the spinner. Default: 20px.
  • --sos-spinner-border-color-light: Color of the spinner's main border. Default: #f0f0f0 (light grey).
  • --sos-spinner-border-top-color: Color of the spinner's top border (spinning part). Default: var(--color-accent) (yellow).
  • --sos-spinner-margin-right: Right margin of the spinner when next to a label. Default: 0.5rem.
  • --sos-icon-size: Size (width and height) of the success and error icons. Default: 20px.
  • --sos-icon-stroke: Stroke width of the success and error icons' checkmark and X shapes. Default: 2px. 

:root {
  /* Your custom variable overrides here */
  --sos-spinner-border-top-color: #e74c3c; /* Red spinner */
}

NPM Package

SpinOnSubmitJS is available on NPM: 

npm install spinonsubmitjs

GitHub Repository

SpinOnSubmitJS on GitHub