Add loading bar or loadind screen on SvelteKit navigation
# sveltekit-top-loading
A navigation progress bar and optional fullscreen loading screen for Svelte 5 and SvelteKit 2.12+ / 3. Uses NProgress and the reactive `$app/state` navigation state.
# About this project
Maintained by [Vinicius R. Vieira (@vinnycrazzy)](https://github.com/vinnycrazzy) in [sveltekit-top-loading](https://github.com/vinnycrazzy/sveltekit-top-loading).
This project is based on and inspired by [sveltekit-top-loader](https://github.com/tsriram/sveltekit-top-loader), created by **Sriram Thiagarajan (@tsriram)**. It continues that work with a SvelteKit 3 development setup, Svelte 5 runes, navigation fixes, and a fullscreen loading screen.
# What's new
* SvelteKit 3.1 and Svelte 5.57 development setup, with TypeScript 6 and Vite 8. * Navigation tracking through `$app/state`, including cancelled navigation and error pages. * Fullscreen loading screen with a logo, centered spinner, and configurable colors and message. * Custom fullscreen content through Svelte snippets. * Configurable display delay to avoid flashes during fast navigation. * Reactive styling, accessible loading messages, and reduced-motion support. * Browser tests covering navigation and fullscreen behavior on desktop and mobile.
# Install
Using pnpm:
pnpm add sveltekit-top-loading
Or npm:
npm install sveltekit-top-loading
Requires **Svelte 5** and **SvelteKit 2.12+ or 3**. These registry installation commands become available after the first npm release.
Svelte 4 is no longer supported. Developing this repository requires Node 22.17+ (Node 24 recommended), pnpm 12, and TypeScript 6. The demo uses SvelteKit 3.1 and Svelte 5.57.
# Usage
Mount **one instance** in your root `src/routes/+layout.svelte`:
<script lang="ts"> import type { Snippet } from 'svelte'; import { SvelteKitTopLoader } from 'sveltekit-top-loading';
let { children }: { children: Snippet } = $props(); </script>
<SvelteKitTopLoader /> {@render children()}
No separate CSS import is required. Keep the loader in the root layout so it stays mounted between pages.
# Fullscreen with a logo
Place your logo in `static/logo.svg`. Supply a URL that includes your application's base path when applicable.
<script lang="ts"> import type { Snippet } from 'svelte'; import { SvelteKitTopLoader } from 'sveltekit-top-loading';
let { children }: { children: Snippet } = $props(); </script>
<SvelteKitTopLoader fullscreen logo="/logo.svg" logoAlt="My application" logoWidth={140} background="#ffffff" foreground="#172b3a" color="#1264a3" label="Carregando página…" delay={150} /> {@render children()}
The screen fills the viewport, with a centered logo, spinner and message. The top progress bar remains visible. `showSpinner={false}` hides the spinner in either mode. The screen is a visual indicator and does not trap focus, lock scrolling, or block interaction with the current page.
# Custom fullscreen content
A Svelte snippet replaces the logo and centered spinner. The message and top bar remain:
<script lang="ts"> import type { Snippet } from 'svelte'; import { SvelteKitTopLoader } from 'sveltekit-top-loading';
let { children }: { children: Snippet } = $props(); </script>
<SvelteKitTopLoader fullscreen label="Preparing your workspace…"> <div class="brand">My application</div> </SvelteKitTopLoader> {@render children()}
Exported `TopLoaderProps` provides the component's TypeScript API.
More details - (https://github.com/vinnycrazzy/sveltekit-top-loading).