Svelte Loading Spinners

Common errors

• Cannot find module 'svelte-loading-spinners'

  cause The package was not installed, the import path is incorrect, or the module resolution in your build environment is misconfigured.
  fix Ensure the package is correctly installed via `npm install svelte-loading-spinners` or `yarn add svelte-loading-spinners`. Double-check the import statement for typos: `import { ComponentName } from 'svelte-loading-spinners';`.

• 'Jumper' is not exported from 'svelte-loading-spinners'

  cause This error occurs when attempting to use a default import for a component that is a named export, or when the component name is misspelled.
  fix Use a named import with curly braces for all components: `import { Jumper } from 'svelte-loading-spinners';`. Verify the component name is correctly capitalized.

• ReferenceError: $navigating is not defined

  cause This issue arises when attempting to access the `$navigating` store, which is part of SvelteKit's `$app/stores`, in an environment where SvelteKit is not active or correctly configured, or if `$app/stores` was not imported.
  fix If using SvelteKit, ensure `import { navigating } from '$app/stores';` is present in your script. If not using SvelteKit, you cannot use `$navigating` and must manage spinner visibility using alternative methods (e.g., local component state).

Warnings

• gotcha Some spinner components, specifically `Circle2` and `Circle3`, feature unique sets of props (e.g., `colorOuter`, `ballTopLeft`) that differ from the standard `size`, `color`, `unit`, and `duration` props shared by most other spinners. Assuming universal props will lead to unstyled or incorrectly animated spinners.
  Fix: Always refer to the 'List of available spinners' section in the package README or the component's TypeScript definitions to understand component-specific props and their usage.
• gotcha The primary integration pattern showcased in the README uses `$app/stores.navigating` to display loading animations during page transitions. This store is exclusive to SvelteKit projects. Using `$navigating` in a vanilla Svelte application without SvelteKit will result in a `ReferenceError: $navigating is not defined`.
  Fix: For vanilla Svelte applications, manage spinner visibility using your own reactive state or integrate with your chosen router's lifecycle events. Ensure SvelteKit is properly set up if you intend to use `$app/stores.navigating`.
• gotcha The package's installation instructions suggest installing it as a development dependency (`npm i --save-dev`). While this is often fine for Svelte components that are compiled into the main bundle, in some specific build configurations or deployment scenarios, it might be safer to install it as a regular dependency (`npm install svelte-loading-spinners`) to guarantee its inclusion in production builds.
  Fix: If you encounter issues where the spinners do not appear in production environments, consider reinstalling the package as a standard dependency: `npm install svelte-loading-spinners` or `yarn add svelte-loading-spinners`.

Install

• npm install svelte-loading-spinners npm
• yarn add svelte-loading-spinners yarn
• pnpm add svelte-loading-spinners pnpm

Imports

• Jumper
  wrong:

  import Jumper from 'svelte-loading-spinners'; // Not a default export

  correct:

  import { Jumper } from 'svelte-loading-spinners';

  Most spinners are named exports. Attempting a default import will result in an error.
• BarLoader
  wrong:

  const { BarLoader } = require('svelte-loading-spinners'); // Primarily targets ESM environments

  correct:

  import { BarLoader } from 'svelte-loading-spinners';

  The library primarily targets ESM environments, which are typical for modern Svelte and SvelteKit projects. CommonJS `require` might not work directly without proper transpilation or configuration.
• Circle2
  wrong:

  import { Circle2 } from 'svelte-loading-spinners/src/Circle2.svelte'; // Direct component path is not recommended or necessary

  correct:

  import { Circle2 } from 'svelte-loading-spinners';

  All individual spinner components are re-exported from the main `svelte-loading-spinners` package entry point, simplifying imports.

Quickstart

Demonstrates integrating `svelte-loading-spinners` for SvelteKit page navigation detection and manual task simulation, using `Jumper` and `Wave` components. This example should be placed in a SvelteKit `+layout.svelte` file.

<!-- src/routes/+layout.svelte -->
<script lang="ts">
  import { Jumper, Wave } from 'svelte-loading-spinners';
  import { navigating } from '$app/stores'; // SvelteKit specific store for navigation status

  // Simulate a delay or background task for demonstration if not relying solely on SvelteKit navigation
  let showManualSpinner = false;
  async function simulateLoading() {
    showManualSpinner = true;
    await new Promise(resolve => setTimeout(resolve, 2000)); // Simulate a 2-second load
    showManualSpinner = false;
  }
</script>

<nav>
  <a href="/">Home</a>
  <a href="/about">About</a>
  <button on:click={simulateLoading}>Simulate Task</button>
</nav>

<!-- Show spinner during SvelteKit navigation -->
{#if $navigating}
  <div class="spinner-overlay kit-nav">
    <Jumper size="60" color="#FF3E00" unit="px" duration="1s" />
    <p>Loading page...</p>
  </div>
{/if}

<!-- Show spinner for manual tasks -->
{#if showManualSpinner}
  <div class="spinner-overlay manual-task">
    <Wave size="80" color="blue" />
    <p>Processing data...</p>
  </div>
{/if}

<slot />

<style>
  .spinner-overlay {
    position: fixed;
    top: 0;
    left: 0;
    width: 100vw;
    height: 100vh;
    display: flex;
    flex-direction: column;
    justify-content: center;
    align-items: center;
    background-color: rgba(255, 255, 255, 0.9);
    z-index: 1000;
  }
  .kit-nav { background-color: rgba(255, 255, 255, 0.9); }
  .manual-task { background-color: rgba(0, 0, 0, 0.7); color: white; }
  nav { padding: 1rem; background: #eee; }
  nav a, nav button { margin-right: 1rem; }
</style>