svelte-html-router

Lightweight Svelte 5 router with history and hash mode, dynamic parameters, and navigation guards.

Features

Dual mode: history (default) and hash
Dynamic route parameters (/user/:id)
Automatic query parameter parsing
Navigation guards (beforeEach)
Link interception (auto-hijacks <a> clicks)
Wildcard routes (*) and redirects
Base path prefix
Full TypeScript type definitions
Svelte 5 Runes compatible

Installation

npm Install

# npm
npm install svelte-html-router

# cnpm（国内镜像）
cnpm install svelte-html-router

# yarn
yarn add svelte-html-router

# pnpm
pnpm add svelte-html-router

Peer Dependencies

Make sure the following dependencies are installed:

npm install svelte

ES Module Import

import { createRouter, RouterView, RouterLink } from 'svelte-html-router'

CommonJS Require

const { createRouter, RouterView, RouterLink } = require('svelte-html-router')

CDN Usage

You can also use it directly via CDN (for quick prototyping or online demos):

<script src="https://unpkg.com/svelte-html-router@1.2.0/dist/svelte-html-router.iife.js"></script>

Quick Start

import { createRouter, RouterView } from 'svelte-html-router'
import Home from './views/Home.svelte'
import About from './views/About.svelte'

const router = createRouter([
  { path: '/', name: 'home', component: Home },
  { path: '/about', name: 'about', component: About },
])

// App.svelte 中使用
// <RouterView {router} />

createRouter

Create a router instance. Accepts an array of route records or a configuration object.

Example

createRouter(options: RouterOptions | RouteRecord[]): RouterInstance

RouterOptions

Property	Type	Default	Description
`routes`	`RouteRecord[]`	—	Route records array (required)
`mode`	`'history' \| 'hash'`	`'history'`	Routing mode
`base`	`string`	`''`	Path prefix (history mode only)

Example

// 简写：直接传数组（默认 history 模式）
const router = createRouter([
  { path: '/', component: Home },
])

// 完整配置
const router = createRouter({
  mode: 'hash',
  base: '/app',
  routes: [
    { path: '/', component: Home },
    { path: '/user/:id', component: User },
    { path: '*', component: NotFound },
  ],
})

RouteRecord

Route record definition.

Property	Type	Required	Description
`path`	`string`	Yes	Route path, supports :param dynamic params and * wildcard
`name`	`string`	—	Route name
`component`	`SvelteComponent`	Yes	Svelte component for this route
`meta`	`Record<string, any>`	—	Route metadata
`redirect`	`string`	—	Redirect target path

RouteLocation

Current route location info, subscribe via router.current.

Property	Type	Description
`path`	`string`	Current path
`name`	`string`	Matched route name
`params`	`Record<string, string>`	Dynamic parameters
`query`	`Record<string, string>`	Query parameters
`meta`	`Record<string, any>`	Route metadata
`matched`	`RouteRecord \| null`	Matched route record

RouterView

Route outlet component that renders the currently matched route component.

Props

Property	Type	Required	Description
`router`	`RouterInstance`	Yes	Router instance

Example

<!-- App.svelte -->
<script>
  import { RouterView } from 'svelte-html-router'
  import { router } from './routes'
</script>

<RouterView {router} />

RouterLink

Navigation link component with automatic active state highlighting.

Props

Property	Type	Default	Description
`to`	`string`	—	Target path (required)
`class`	`string`	`''`	Custom CSS class
`activeClass`	`string`	`'router-link-active'`	CSS class applied when active
`router`	`RouterInstance`	—	Router instance (optional, obtained from context by default)

Example

<script>
  import { RouterLink } from 'svelte-html-router'
</script>

<RouterLink to="/">首页</RouterLink>
<RouterLink to="/about" activeClass="current">关于</RouterLink>

Router Instance Methods

Method	Parameters	Description
`push(path)`	`path: string`	Navigate to a new path (creates history entry)
`replace(path)`	`path: string`	Navigate to a new path (replaces current history entry)
`back()`	—	Go back one step
`forward()`	—	Go forward one step
`go(n)`	`n: number`	Go forward/back n steps
`beforeEach(guard)`	`guard: NavigationGuard`	Register a global navigation guard
`buildHref(path)`	`path: string`	Build href string (based on route mode)
`init()`	—	Initialize router (listen to popstate / hashchange)
`destroy()`	—	Destroy router (remove event listeners)

Properties

Property	Type	Description
`current`	`Readable<RouteLocation>`	Current route location (use $current to subscribe)
`routes`	`RouteRecord[]`	All route records
`mode`	`'history' \| 'hash'`	Current routing mode

Navigation Guards

Type

type NavigationGuard = (
  to: RouteLocation,
  from: RouteLocation
) => boolean | string | void | Promise<boolean | string | void>

Return Value

Return Value	Effect
`void` / `undefined`	Allow, continue navigation
`false`	Cancel navigation
`string`（path）	Redirect to the specified path

Example

router.beforeEach((to, from) => {
  // 需要登录的页面
  if (to.meta.requiresAuth && !isLoggedIn()) {
    return '/login' // 重定向到登录页
  }
  // 放行
})

Route Mode

History Mode (default)

Uses the browser History API with clean URLs (no # prefix). Requires server-side configuration to fallback all paths to index.html.

# Nginx 配置
location / {
  try_files $uri $uri/ /index.html;
}

Hash Mode

Uses URL hash (#), no server configuration needed, suitable for static hosting.

const router = createRouter({
  mode: 'hash',
  routes: [...],
})