Skip to content

Instantly share code, notes, and snippets.

@jreviews
Last active April 1, 2024 22:22
Show Gist options
  • Save jreviews/1a2e15de64a92526ad52cc4b75ea492a to your computer and use it in GitHub Desktop.
Save jreviews/1a2e15de64a92526ad52cc4b75ea492a to your computer and use it in GitHub Desktop.
htmx loading states extension

htmx loading states extension

The loading-states extension allows you to easily manage loading states while a request is in flight, including disabling elements, and adding and removing CSS classes.

Using the extension

Add the hx-ext="loading-states" attribute to the body tag or to any parent element containing your htmx attributes.

Add the following class to your stylesheet to make sure elements are hidden by default:

[data-loading] {
  display: none;
}

Supported attributes

  • data-loading

    Shows the element. The default style is inline-block, but it's possible to use any display style by specifying it in the attribute value.

    <div data-loading>loading</div>
    
    <div data-loading="block">loading</div>
    
    <div data-loading="flex">loading</div>
  • data-loading-class

    Adds, then removes, CSS classes to the element:

    <div class="transition-all ease-in-out duration-600" data-loading-class="bg-gray-100 opacity-80">
    ...
    </div>
  • data-loading-class-remove

    Removes, then adds back, CSS classes from the element.

    <div class="p-8 bg-gray-100 transition-all ease-in-out duration-600" data-loading-class-remove="bg-gray-100">
    ...
    </div>
  • data-loading-disable

    Disables an element for the duration of the request.

    <button data-loading-disable>Submit</button>
  • data-loading-delay

    Some actions may update quickly and showing a loading state in these cases may be more of a distraction. This attribute ensures that the loading state changes are applied only after 200ms if the request is not finished. The default delay can be modified through the attribute value and expressed in milliseconds:

    <button type="submit" data-loading-disable data-loading-delay="1000">Submit</button>

    You can place the data-loading-delay attribute directly on the element you want to disable, or in any parent element.

  • data-loading-target

    Allows setting a different target to apply the loading states. The attribute value can be any valid CSS selector. The example below disables the submit button and shows the loading state when the form is submitted.

    <form hx-post="/save"
      data-loading-target="#loading"
      data-loading-class-remove="hidden">
      
      <button type="submit" data-loading-disable>Submit</button>
    
    </form>
    
    <div id="loading" class="hidden">Loading ...</div>
  • data-loading-path

    Allows filtering the processing of loading states only for specific requests based on the request path.

    <form hx-post="/save">
      <button type="submit" data-loading-disable data-loading-path="/save">Submit</button>
    </form>

    You can place the data-loading-path attribute directly on the loading state element, or in any parent element.

    <form hx-post="/save" data-loading-path="/save">
      <button type="submit" data-loading-disable>Submit</button>
    </form>
  • data-loading-states

    This attribute is optional and it allows defining a scope for the loading states so only elements within that scope are processed.

    <div data-loading-states>
      <div hx-get=""></div>
      <div data-loading>loading</div>
    </div>
    
    <div data-loading-states>
      <div hx-get=""></div>
      <div data-loading>loading</div>
    </div>
    
    <form data-loading-states hx-post="">
      <div data-loading>loading</div>
    </form>

And here's the extension code ...

(function () {
  let loadingStatesUndoQueue = [];

  function loadingStateContainer(target) {
    return htmx.closest(target, '[data-loading-states]') || document.body;
  }

  function mayProcessUndoCallback(target, callback) {
    if (document.body.contains(target)) {
      callback();
    }
  }

  function mayProcessLoadingStateByPath(elt, requestPath) {
    const pathElt = htmx.closest(elt, '[data-loading-path]');
    if (!pathElt) {
      return true;
    }

    return pathElt.getAttribute('data-loading-path') === requestPath;
  }

  function queueLoadingState(sourceElt, targetElt, doCallback, undoCallback) {
    const delayElt = htmx.closest(sourceElt, '[data-loading-delay]');
    if (delayElt) {
      const delayInMilliseconds = delayElt.getAttribute('data-loading-delay') || 200;
      const timeout = setTimeout(() => {
        doCallback();

        loadingStatesUndoQueue.push(() => {
          mayProcessUndoCallback(targetElt, () => undoCallback());
        });
      }, delayInMilliseconds);

      loadingStatesUndoQueue.push(() => {
        mayProcessUndoCallback(targetElt, () => clearTimeout(timeout));
      });
    } else {
      doCallback();
      loadingStatesUndoQueue.push(() => {
        mayProcessUndoCallback(targetElt, () => undoCallback());
      });
    }
  }

  function getLoadingStateElts(loadingScope, type, path) {
    return Array.from(htmx.findAll(loadingScope, `[${type}]`)).filter((elt) =>
      mayProcessLoadingStateByPath(elt, path)
    );
  }

  function getLoadingTarget(elt) {
    if (elt.getAttribute('data-loading-target')) {
      return Array.from(htmx.findAll(elt.getAttribute('data-loading-target')));
    }
    return [elt];
  }

  htmx.defineExtension('loading-states', {
    onEvent: function (name, evt) {
      if (name === 'htmx:beforeRequest') {
        const container = loadingStateContainer(evt.target);

        const loadingStateTypes = [
          'data-loading',
          'data-loading-class',
          'data-loading-class-remove',
          'data-loading-disable'
        ];

        let loadingStateEltsByType = {};

        loadingStateTypes.forEach((type) => {
          loadingStateEltsByType[type] = getLoadingStateElts(
            container,
            type,
            evt.detail.pathInfo.path
          );
        });

        loadingStateEltsByType['data-loading'].forEach((sourceElt) => {
          getLoadingTarget(sourceElt).forEach((targetElt) => {
            queueLoadingState(
              sourceElt,
              targetElt,
              () =>
                (targetElt.style.display =
                  sourceElt.getAttribute('data-loading') || 'inline-block'),
              () => (targetElt.style.display = 'none')
            );
          });
        });

        loadingStateEltsByType['data-loading-class'].forEach((sourceElt) => {
          const classNames = sourceElt.getAttribute('data-loading-class').split(' ');

          getLoadingTarget(sourceElt).forEach((targetElt) => {
            queueLoadingState(
              sourceElt,
              targetElt,
              () => classNames.forEach((className) => targetElt.classList.add(className)),
              () => classNames.forEach((className) => targetElt.classList.remove(className))
            );
          });
        });

        loadingStateEltsByType['data-loading-class-remove'].forEach((sourceElt) => {
          const classNames = sourceElt.getAttribute('data-loading-class-remove').split(' ');

          getLoadingTarget(sourceElt).forEach((targetElt) => {
            queueLoadingState(
              sourceElt,
              targetElt,
              () => classNames.forEach((className) => targetElt.classList.remove(className)),
              () => classNames.forEach((className) => targetElt.classList.add(className))
            );
          });
        });

        loadingStateEltsByType['data-loading-disable'].forEach((sourceElt) => {
          getLoadingTarget(sourceElt).forEach((targetElt) => {
            queueLoadingState(
              sourceElt,
              targetElt,
              () => (targetElt.disabled = true),
              () => (targetElt.disabled = false)
            );
          });
        });
      }

      if (name === 'htmx:afterOnLoad') {
        while (loadingStatesUndoQueue.length > 0) {
          loadingStatesUndoQueue.shift()();
        }
      }
    }
  });
})();
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment