sv-router

https://sv-router.vercel.app/
Admin
sv-router is a modern, feature-rich, and intuitive routing library for Svelte single-page...
Tokens:16,515
Snippets:237
Trust Score:7.8
Update:5 months ago
Show doc for...
Tokens:
Raw
### Create New sv-router Project with deno

Source: https://sv-router.vercel.app/guide/getting-started

Use this command to start a new project with sv-router using deno.

```sh
deno run -A npm:create-sv-router@latest
```

--------------------------------

### Install sv-router on Existing Project with deno

Source: https://sv-router.vercel.app/guide/getting-started

Install the sv-router package on an existing project using deno. Requires Svelte 5.

```sh
deno add npm:sv-router
```

--------------------------------

### Create New sv-router Project with bun

Source: https://sv-router.vercel.app/guide/getting-started

Use this command to start a new project with sv-router using bun.

```sh
bun create sv-router
```

--------------------------------

### Dynamic Route File Structure Examples

Source: https://sv-router.vercel.app/guide/file-based/dynamic-routes

Illustrates how to structure files for dynamic routes in both flat and tree modes.

```sh
routes
├── user.[id].svelte                   ➜ /user/123
└── user.[id].post.[postId].svelte     ➜ /user/123/post/456
```

```sh
routes
└── user
   └── [id]
      ├── index.svelte                 ➜ /user/123
      └── post
         └── [postId].svelte           ➜ /user/123/post/456
```

--------------------------------

### Create New sv-router Project with npm

Source: https://sv-router.vercel.app/guide/getting-started

Use this command to start a new project with sv-router using npm.

```sh
npm create sv-router@latest
```

--------------------------------

### Install sv-router on Existing Project with bun

Source: https://sv-router.vercel.app/guide/getting-started

Install the sv-router package on an existing project using bun. Requires Svelte 5.

```sh
bun add sv-router
```

--------------------------------

### Create New sv-router Project with pnpm

Source: https://sv-router.vercel.app/guide/getting-started

Use this command to start a new project with sv-router using pnpm.

```sh
pnpm create sv-router
```

--------------------------------

### Install sv-router on Existing Project with pnpm

Source: https://sv-router.vercel.app/guide/getting-started

Install the sv-router package on an existing project using pnpm. Requires Svelte 5.

```sh
pnpm add sv-router
```

--------------------------------

### Create New sv-router Project with yarn

Source: https://sv-router.vercel.app/guide/getting-started

Use this command to start a new project with sv-router using yarn.

```sh
yarn create sv-router
```

--------------------------------

### Install sv-router on Existing Project with npm

Source: https://sv-router.vercel.app/guide/getting-started

Install the sv-router package on an existing project using npm. Requires Svelte 5.

```sh
npm install sv-router
```

--------------------------------

### Install sv-router on Existing Project with yarn

Source: https://sv-router.vercel.app/guide/getting-started

Install the sv-router package on an existing project using yarn. Requires Svelte 5.

```sh
yarn add sv-router
```

--------------------------------

### Ignore Files via CLI

Source: https://sv-router.vercel.app/guide/file-based/configuration

When using the CLI, pass the `ignore` option as a string argument. Multiple ignore patterns can be separated by commas. This example ignores Svelte files starting with a capital letter.

```json
"postinstall": "sv-router --ignore '[A-Z].*\.svelte$'" // You can have multiple ones separated by commas
```

--------------------------------

### Route Structure with Layout

Source: https://sv-router.vercel.app/guide/file-based/layouts

Example of how to structure routes with a layout component. The `layout.svelte` file wraps other routes at the same level.

```sh
routes
└── about
   ├── index.svelte
   ├── layout.svelte
   ├── team.svelte
   └── work.svelte
```

--------------------------------

### Add postinstall Script for Route Generation

Source: https://sv-router.vercel.app/guide/file-based/manual-setup

Include a `postinstall` script in package.json to automatically generate routes when dependencies are installed. This ensures routes are up-to-date in CI environments and for new contributors.

```json
{
	"scripts": {
		"postinstall": "sv-router"
	}
}
```

--------------------------------

### Ignore Files with RegExp

Source: https://sv-router.vercel.app/guide/file-based/configuration

Use the `ignore` option with an array of regular expressions to exclude specific files from route generation. This example ignores Svelte files starting with a capital letter.

```typescript
router({ ignore: [/[A-Z].*\.svelte$/] )}
```

--------------------------------

### Custom View Transition Animations with CSS

Source: https://sv-router.vercel.app/guide/code-based/view-transitions

Define custom CSS animations for view transitions using `@keyframes` and the `::view-transition-old` and `::view-transition-new` pseudo-elements. This example applies a vertical slide effect.

```css
@keyframes move-out {
	from {
		transform: translateY(0%);
	}

	to {
		transform: translateY(-100%);
	}
}

@keyframes move-in {
	from {
		transform: translateY(100%);
	}

	to {
		transform: translateY(0%);
	}
}

/* Apply the custom animation to the old and new page states */

::view-transition-old(root) {
	animation: 0.4s ease-in both move-out;
}

::view-transition-new(root) {
	animation: 0.4s ease-in both move-in;
}
```

--------------------------------

### Defining Route Hooks in sv-router

Source: https://sv-router.vercel.app/guide/code-based/hooks

Example of defining various hooks (beforeLoad, afterLoad, onPreload, onError) within a nested route configuration.

```typescript
export const { p, navigate, isActive, route } = createRouter({
	'/': Home,
	'/about': {
		'/': About,
		hooks: {
			beforeLoad() {
				// Execute before route loads
			},
			afterLoad() {
				// Execute after route loads
			},
			onPreload() {
				// Execute when the route is preloaded
			},
			onError() {
				// Execute when route components fail to load or beforeLoad hooks throw an error
			},
		},
	},
});
```

--------------------------------

### Define Route Hooks in hooks.ts

Source: https://sv-router.vercel.app/guide/file-based/hooks

Create a `hooks.ts` file within your route directory to define lifecycle hooks for route activation. This example shows the basic structure for `beforeLoad`, `afterLoad`, `onPreload`, and `onError` hooks.

```typescript
import type { Hooks } from 'sv-router';

export default {
	beforeLoad() {
		// Execute before route loads
	},
	afterLoad() {
		// Execute after route loads
	},
	onPreload() {
		// Execute when the route is preloaded
	},
	onError() {
		// Execute when route components fail to load or beforeLoad hooks throw an error
	},
} satisfies Hooks;
```

--------------------------------

### Define Route Metadata

Source: https://sv-router.vercel.app/guide/file-based/route-metadata

Use the `meta` property in a `meta.ts` file to define metadata for a route. This example sets the route to be non-public.

```typescript
import type { RouteMeta } from 'sv-router';

export default {
	public: false,
} satisfies RouteMeta;
```

--------------------------------

### Manage Search Parameters with sv-router

Source: https://sv-router.vercel.app/guide/code-based/search-params

Use the `searchParams` object to add, delete, and get URL parameters. Changes automatically update the URL.

```typescript
import { searchParams } from 'sv-router';

// Add a parameter
searchParams.append('hello', 'world');

// Remove a parameter
searchParams.delete('hello');

// React to parameter changes
$effect(() => {
	// This effect will re-run whenever the 'hello' parameter changes
	const value = searchParams.get('hello');
	console.log('Hello parameter is now:', value);
});
```

--------------------------------

### Block Navigation with Context in beforeLoad

Source: https://sv-router.vercel.app/guide/file-based/hooks

Access the context object within the `beforeLoad` hook to conditionally block navigation based on route information like `pathname`, `search`, `hash`, `state`, `replace`, and `meta`. This example redirects non-admin users away from protected routes.

```typescript
function beforeLoad({ pathname, search, hash, state, replace, meta }) {
	if (!admin && pathname !== '/') {
		throw navigate('/');
	}
}
```

--------------------------------

### Create Router with Basic Routes

Source: https://sv-router.vercel.app/guide/code-based/route-definition

Initializes the router with basic route definitions for Home and About pages. Import necessary components and the `createRouter` function.

```typescript
import { createRouter } from 'sv-router';
import Home from './routes/Home.svelte';
import About from './routes/About.svelte';

export const { p, navigate, isActive, route } = createRouter({
	'/': Home,
	'/about': About,
});
```

--------------------------------

### Link Navigation with Parameters and Options

Source: https://sv-router.vercel.app/guide/code-based/navigation

Pass parameters and additional options to the `p` function for dynamic route generation.

```svelte
<a
	href={p('/post/:slug', { params: { slug: '123' }, search: { q: 'hello' } })}
	data-replace
	data-state='{ "from": "home" }'>
	A post
</a>
```

--------------------------------

### createRouter(routes)

Source: https://sv-router.vercel.app/reference/index

Initializes a new router instance with a given routes configuration. It returns an object with methods for path construction, navigation, route activation checking, component preloading, and accessing current route information.

```APIDOC
## createRouter(routes)

### Description
Sets up a new router instance with the given routes configuration.

### Parameters
* `routes` - An object mapping paths to components or nested routes

### Returns
A router API object with the following properties:
* `p` - Path constructor
* `navigate` - Navigation function
* `isActive` - Route activation checker
* `preload` - Preload route components
* `route` - Current route information
```

--------------------------------

### Link Navigation with Parameters and Options

Source: https://sv-router.vercel.app/guide/file-based/navigation

Pass parameters, search queries, and state to the `p` function for dynamic link generation. Attributes like `data-replace` and `data-state` can also be used.

```svelte
<a
	href={p('/post/:slug', { params: { slug: '123' }, search: { q: 'hello' } })}
	data-replace
	data-state={`{ "from": "home" }`}
>
	A post
</a>
```

--------------------------------

### navigate(path, options?)

Source: https://sv-router.vercel.app/reference/index

Programmatically navigates the user to a specified route. This function returns a promise that resolves once the navigation is complete, including any redirects and lazy-loaded components.

```APIDOC
## navigate(path, options?)

### Description
Programmatically navigate to a route. Returns a promise that resolves once the navigation is complete, including any redirects triggered by `beforeLoad` hooks and lazy-loaded route components.

### Parameters
* `path | number` - Either: 
  * A string path to navigate to, or
  * A number representing steps to navigate in history (negative for back, positive for forward)
* `options` - (Optional) Navigation options 
  * `replace` - Replace current history entry instead of pushing
  * `search` - Query string
  * `state` - History state to save
  * `hash` - URL hash fragment
  * `scrollToTop` - Scroll behavior (`"auto" | "instant" | "smooth" | false`)
  * `viewTransition` - Enable view transition (`boolean`)
  * `params` - Parameters to substitute in the path

### Returns
`Promise<Navigation>` - Resolves when the full navigation (including redirects and code splitting) is complete
```

--------------------------------

### Route Group with Layout, Hooks, and Meta

Source: https://sv-router.vercel.app/guide/file-based/route-groups

Demonstrates a route group containing a layout, hooks, and meta files, all of which are associated with the routes within the group without affecting the URL.

```svelte
routes
└── _dashboard
   ├── layout.svelte
   ├── hooks.ts
   ├── meta.ts
   └── index.svelte
```

--------------------------------

### Configure CLI via package.json

Source: https://sv-router.vercel.app/guide/file-based/configuration

If not using Vite or the config can't be read, pass options directly to the CLI in your `package.json` scripts. CLI arguments override Vite config.

```json
{
	"scripts": {
		"postinstall": "sv-router --path src/pages"
	}
}
```

--------------------------------

### Define a Basic Catch-All Route

Source: https://sv-router.vercel.app/guide/code-based/catch-all-routes

Use the `*` symbol to define a catch-all route that handles any unmatched paths. This is useful for displaying a 404 Not Found page.

```typescript
'*': NotFound,

```

--------------------------------

### Programmatic Navigation with Parameters and Options

Source: https://sv-router.vercel.app/guide/code-based/navigation

Pass parameters and additional options to the `navigate` function for flexible programmatic navigation.

```typescript
navigate('/post/:slug', {
	params: {
		slug: '123',
	},
	replace: true,
	search: { q: 'hello' },
	state: { from: 'home' },
	hash: 'first-section',
});
```

--------------------------------

### Integrate Router Component in App.svelte

Source: https://sv-router.vercel.app/guide/code-based/manual-setup

Import the Router component and your custom router configuration into your application's entry point. Add navigation links using standard anchor tags.

```svelte
<script lang="ts">
	import { Router } from 'sv-router';
	import './router.ts';
</script>

<a href="/">Home</a>
<a href="/about">About</a>

<Router />
```

--------------------------------

### Layout Exclusion for Dynamic and Catch-all Routes

Source: https://sv-router.vercel.app/guide/file-based/layouts

Shows how to use parentheses to exclude dynamic and catch-all routes from inheriting their parent layout.

```sh
# Dynamic route that ignores parent layout
routes
└── ([id]).svelte

# Catch-all route that ignores parent layout
routes
└── ([...notfound]).svelte
```

--------------------------------

### Enable Hash-Based Routing

Source: https://sv-router.vercel.app/guide/code-based/basename

Use a '#' as the base for the router to switch to hash-based routing. Routes are matched by the URL's hash instead of its pathname, which is useful for file:// URLs.

```svelte
<script lang="ts">
	import { Router } from 'sv-router';
</script>

<Router base="#" />
```

--------------------------------

### Basic Link Navigation

Source: https://sv-router.vercel.app/guide/code-based/navigation

Use standard anchor tags for basic navigation between pages.

```svelte
<a href="/about">About</a>
```

--------------------------------

### Programmatic Route Checking with isActive

Source: https://sv-router.vercel.app/guide/code-based/active-route

Use the `isActive` function for programmatic route checking, which supports route parameters and pattern matching. `isActive.startsWith` checks if the current route begins with a specified path.

```ts
import { isActive } from './router';

// Returns true when on '/about'
isActive('/about');

// Returns true when on '/post/123'
isActive('/post/:slug', { slug: '123' });

// Returns true when on '/post/*'
isActive('/post/:slug');

// Returns true when on '/about' or '/about/*'
isActive.startsWith('/about');
```

--------------------------------

### Define a Catch-All Route

Source: https://sv-router.vercel.app/guide/file-based/catch-all-routes

Use the spread syntax `[...slug].svelte` to create a catch-all route. The unmatched part of the URL can be accessed via `route.params`.

```svelte
routes
└── [...notfound].svelte               ➜ /any-path
```

--------------------------------

### p(path, params?)

Source: https://sv-router.vercel.app/reference/index

Constructs a URL path with type-safe parameter substitution. It allows for dynamic path generation based on route definitions and provided parameters.

```APIDOC
## p(path, params?)

### Description
Constructs a path with type-safe parameter substitution.

### Parameters
* `path` - The route path
* `options` - (Optional) Navigation options 
  * `params` - Parameters to substitute in the path
  * `search` - Query string
  * `hash` - URL hash fragment

### Returns
A string representing the constructed path
```

--------------------------------

### Organizing Routes with Route Groups

Source: https://sv-router.vercel.app/guide/file-based/route-groups

Use folders prefixed with an underscore to group related routes. The folder name is ignored in the URL, allowing routes within to appear at the root level.

```svelte
routes
├── index.svelte        ➜ /
└── _marketing
    ├── about.svelte    ➜ /about
    └── contact.svelte  ➜ /contact
```

--------------------------------

### router(options?)

Source: https://sv-router.vercel.app/reference/vite-plugin

A Vite plugin that automatically generates route definitions from your file system structure. It accepts an optional configuration object to customize its behavior.

```APIDOC
## router(options?)

### Description
A Vite plugin that automatically generates route definitions from your file system structure.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* `options` - (Optional) Configuration object for the router plugin. See `RouterOptions` for details.

### Returns
A Vite plugin
```

--------------------------------

### Generate Routes Script in package.json

Source: https://sv-router.vercel.app/guide/file-based/manual-setup

Create a script in your package.json to generate routes using the sv-router CLI. This is useful for bundlers other than Vite.

```json
{
	"scripts": {
		"gen-routes": "sv-router"
	}
}
```

--------------------------------

### route

Source: https://sv-router.vercel.app/reference/index

Provides access to information about the current route, including parameters, pathname, search query, state, and hash fragment.

```APIDOC
## route

### Description
An object containing information about the current route.

### Properties
* `params` - Non-strict parameters from the current route
* `getParams(pathname: string)` - Strict parameters from the current route
* `pathname` - Current path
* `search` - Query string portion of the URL
* `state` - History state
* `hash` - Hash fragment of the URL
```

--------------------------------

### Type-Safe Link Navigation with `p`

Source: https://sv-router.vercel.app/guide/code-based/navigation

Leverage the `p` function for type-safe navigation, providing auto-complete and type checking for your routes.

```svelte
<script lang="ts">
	import { p } from '../router';
</script>

<a href={p('/about')}>About</a>
```

--------------------------------

### Enable View Transitions with data-view-transition Attribute

Source: https://sv-router.vercel.app/guide/code-based/view-transitions

Add the `data-view-transition` attribute to an anchor tag to enable view transitions for that link. This method also falls back to regular navigation if unsupported.

```svelte
<a href={p('/about')} data-view-transition>About</a>
```

--------------------------------

### Router API Methods

Source: https://sv-router.vercel.app/reference

Details the methods available on the router API object returned by `createRouter`.

```APIDOC
## Router API Methods

### `p(path, params?)`

#### Description
Constructs a path with type-safe parameter substitution.

#### Parameters
* `path` - The route path
* `options` - (Optional) Navigation options 
    * `params` - Parameters to substitute in the path
    * `search` - Query string
    * `hash` - URL hash fragment

#### Returns
A string representing the constructed path

### `navigate(path, options?)`

#### Description
Programmatically navigate to a route. Returns a promise that resolves once the navigation is complete, including any redirects triggered by `beforeLoad` hooks and lazy-loaded route components.

#### Parameters
* `path | number` - Either: 
    * A string path to navigate to, or
    * A number representing steps to navigate in history (negative for back, positive for forward)
* `options` - (Optional) Navigation options 
    * `replace` - Replace current history entry instead of pushing
    * `search` - Query string
    * `state` - History state to save
    * `hash` - URL hash fragment
    * `scrollToTop` - Scroll behavior (`"auto" | "instant" | "smooth" | false`)
    * `viewTransition` - Enable view transition (`boolean`)
    * `params` - Parameters to substitute in the path

#### Returns
`Promise<Navigation>` - Resolves when the full navigation (including redirects and code splitting) is complete

### `isActive(path, params?)`

#### Description
Checks if a given path is currently active.

#### Parameters
* `path` - The route to check
* `params` - (Optional) Parameters to substitute in the path

#### Returns
Boolean indicating if the route is active

##### Methods
* `startsWith(path: string, params?: Record<string, string | number>): boolean` - Returns true if the current route starts with the given path and parameters.

### `preload(path)`

#### Description
Preload route components.

#### Parameters
* `path` - The route to preload

#### Returns
Promise that resolves when the route components are preloaded

### `route`

#### Description
An object containing information about the current route.

#### Properties
* `params` - Non-strict parameters from the current route
* `getParams(pathname: string)` - Strict parameters from the current route
* `pathname` - Current path
* `search` - Query string portion of the URL
* `state` - History state
* `hash` - Hash fragment of the URL
```

--------------------------------

### Flat Mode Route Organization

Source: https://sv-router.vercel.app/guide/file-based/route-definition

Organize routes in a flat structure where all routes are defined at the root level. Filenames directly map to route paths.

```shell
# Flat
routes
├── about.svelte                       ➜ /about
├── about.contact.svelte               ➜ /about/contact
├── about.work.svelte                  ➜ /about/work
└── about.work.mywork.svelte           ➜ /about/work/mywork
```

--------------------------------

### Programmatic Navigation with `navigate`

Source: https://sv-router.vercel.app/guide/code-based/navigation

Use the `navigate` function for navigation triggered by JavaScript events, offering auto-complete and type checking.

```svelte
<script lang="ts">
	import { navigate } from '../router';
</script>

<button onclick={() => navigate('/about')}>About</button>
```

--------------------------------

### Programmatic Preloading with sv-router

Source: https://sv-router.vercel.app/guide/file-based/preloading

Use the `preload` function from `sv-router/generated` to programmatically preload a route. This is useful for scenarios where preloading is not tied to a link interaction.

```typescript
import { preload } from 'sv-router/generated';

await preload('/about');
```

--------------------------------

### Implement Code Splitting with import()

Source: https://sv-router.vercel.app/guide/code-based/code-splitting

Use the `import()` function to dynamically load components for code splitting. This is useful for routes that are not accessed frequently.

```typescript
import { createRouter } from 'sv-router';
import Home from './routes/Home.svelte';
import About from './routes/About.svelte'; 

export const { p, navigate, isActive, route } = createRouter({
	'/': Home,
	'/about': About, 
	'/about': () => import('./routes/About.svelte'), 
});
```

--------------------------------

### Define Routes with Metadata

Source: https://sv-router.vercel.app/guide/code-based/route-metadata

Attach arbitrary data to routes using the `meta` property. This is useful for authentication guards, UI configuration, analytics tracking, and more.

```typescript
export const { p, navigate, isActive, route } = createRouter({
	'/': Home,
	'/about': {
		'/': About,
		meta: {
			public: true,
		},
	},
});
```

--------------------------------

### preload(path)

Source: https://sv-router.vercel.app/reference/index

Preloads the components associated with a specific route path. This can be used for performance optimization by fetching route components ahead of time.

```APIDOC
## preload(path)

### Description
Preload route components.

### Parameters
* `path` - The route to preload

### Returns
Promise that resolves when the route components are preloaded
```

--------------------------------

### Combining Route Groups with Layouts

Source: https://sv-router.vercel.app/guide/file-based/route-groups

Add a `layout.svelte` file inside a route group to wrap all its child routes. This layout will not be exposed in the URL.

```svelte
routes
├── about.svelte             ➜ /about
└── _dashboard
    ├── layout.svelte
    ├── index.svelte         ➜ /
    └── settings.svelte      ➜ /settings
```

--------------------------------

### Tree Mode Route Organization

Source: https://sv-router.vercel.app/guide/file-based/route-definition

Organize routes in a hierarchical directory structure. Nested directories correspond to nested route paths.

```shell
# Tree
routes
└── about
   ├── contact.svelte                  ➜ /about/contact
   ├── index.svelte                    ➜ /about
   └── work
      ├── index.svelte                 ➜ /about/work
      └── mywork.svelte                ➜ /about/work/mywork
```

--------------------------------

### Async Navigation Blocking

Source: https://sv-router.vercel.app/guide/code-based/navigation

Implement asynchronous work within the `blockNavigation` callback to decide whether to allow navigation, such as showing a custom modal.

```svelte
<script lang="ts">
	import { blockNavigation } from 'sv-router';

	$effect(() =>
		blockNavigation(async () => {
			return await showConfirmModal();
		}),
	);
</script>
```

--------------------------------

### Implement Code Splitting with .lazy.svelte Suffix

Source: https://sv-router.vercel.app/guide/file-based/code-splitting

Suffix your route filename with `.lazy.svelte` to enable code splitting for that route. This is useful for routes that are not frequently accessed.

```treeview
routes
├── about.svelte
├── about.lazy.svelte
└── index.svelte
```

--------------------------------

### Enable View Transitions with navigate Function

Source: https://sv-router.vercel.app/guide/code-based/view-transitions

Pass the `viewTransition: true` option to the `navigate` function to enable view transitions. This falls back to a regular navigation if view transitions are not supported.

```typescript
navigate('/about', { viewTransition: true });
```

--------------------------------

### Customizing Active Link Classes

Source: https://sv-router.vercel.app/guide/code-based/active-route

The `className` option in `isActiveLink` supports multiple space-separated classes or dynamic class generation using libraries like `clsx` for advanced styling.

```svelte
<!-- Space-separated classes -->
<a {@attach isActiveLink({ className: 'active highlighted' })}>

<!-- Using clsx for conditional classes -->
<a {@attach isActiveLink({ className: clsx('active', isSpecial && 'special') })}>
```

--------------------------------

### Blocking Tab Close and Navigation

Source: https://sv-router.vercel.app/guide/file-based/navigation

Use the object form of `blockNavigation` with a `beforeUnload` method to prevent tab closing or refreshing. The `onNavigate` method can handle async checks.

```svelte
<script lang="ts">
	import { blockNavigation } from 'sv-router';

	$effect(() =>
		blockNavigation({
			beforeUnload() {
				return false; // prevents tab close
			},
			onNavigate() {
				return await showConfirmModal();
			},
		}),
	);
</script>

NOTE
`beforeUnload` must be synchronous (browser limitation), while `onNavigate` can be async.
```

--------------------------------

### Route Structure with Parent Layout Exclusion

Source: https://sv-router.vercel.app/guide/file-based/layouts

Demonstrates how to exclude a route from inheriting its parent layout by wrapping the route segment in parentheses.

```sh
routes
└── about
   ├── index.svelte                    ➜ Uses layout
   ├── layout.svelte
   └── work
      ├── index.svelte                 ➜ Uses layout
      └── (clients).svelte             ➜ Ignores layout
```

--------------------------------

### Highlight Active Links with isActiveLink

Source: https://sv-router.vercel.app/guide/code-based/active-route

Use the `isActiveLink` attachment on anchor tags to automatically add a CSS class when the link matches the current route. The default class is 'is-active'.

```svelte
<script lang="ts">
	import { isActiveLink } from 'sv-router';
</script>

<a href={p('/about')} {@attach isActiveLink()}>About</a>
```

```svelte
<!-- With custom class name -->
<a href={p('/about')} {@attach isActiveLink({ className: 'custom-class' })}>

<!-- Active when the route starts with '/about' -->
<a href={p('/about')} {@attach isActiveLink({ startsWith: true })}>
```

--------------------------------

### Integrate Router Component in App.svelte

Source: https://sv-router.vercel.app/guide/file-based/manual-setup

Import and use the `Router` component from `sv-router` in your application's entry point component (`App.svelte`). Also, import the generated routes to enable routing.

```svelte
<script lang="ts">
	import { Router } from 'sv-router';
	import 'sv-router/generated';
</script>

<a href="/">Home</a>
<a href="/about">About</a>

<Router />
```

--------------------------------

### Access Dynamic Route Parameters

Source: https://sv-router.vercel.app/guide/code-based/dynamic-routes

Access dynamic route parameters using `route.getParams` for strict matching with a specific pathname, or `route.params` for a partial record of all possible parameters.

```svelte
<script lang="ts">
	import { route } from '../router';

	// Typed as { id: string, postId: string }
	route.getParams('/user/:id/post/:postId');

	// Typed as { id?: string, postId?: string, ... }
	route.params;
</script>
```

--------------------------------

### Blocking Tab Close and Navigation

Source: https://sv-router.vercel.app/guide/code-based/navigation

Use the object form of `blockNavigation` with a `beforeUnload` method to prevent tab closing or refreshing. Note that `beforeUnload` must be synchronous.

```svelte
<script lang="ts">
	import { blockNavigation } from 'sv-router';

	$effect(() =>
		blockNavigation({
			beforeUnload() {
				return false; // prevents tab close
			},
			onNavigate() {
				return await showConfirmModal();
			},
		}),
	);
</script>
```

--------------------------------

### Break Out with Dynamic and Catch-all Routes

Source: https://sv-router.vercel.app/guide/code-based/layouts

The pattern for breaking out of parent layouts also applies to dynamic segments and catch-all routes, allowing for flexible route configuration.

```typescript
// Dynamic route that ignores parent layout
"/(:id)": PostId,

// Catch-all route that ignores parent layout
"(*notfound)": NotFound,
```

--------------------------------

### Manage Head Elements with Svelte

Source: https://sv-router.vercel.app/guide/tips

Use Svelte's native `<svelte:head>` element to dynamically set metadata like page titles and meta tags for each route. This is useful for SEO and user experience.

```svelte
<svelte:head>
	<title>About</title>
	<meta name="description" content="..." />
</svelte:head>
```

--------------------------------

### Configure Vite Plugin for sv-router

Source: https://sv-router.vercel.app/guide/file-based/manual-setup

Add the sv-router plugin to your Vite configuration file to enable file-based routing.

```typescript
import { svelte } from '@sveltejs/vite-plugin-svelte';
import { defineConfig } from 'vite';
import { router } from 'sv-router/vite-plugin'; 

export default defineConfig({
	plugins: [
		svelte(),
		router(), 
	],
});
```

--------------------------------

### Router Component

Source: https://sv-router.vercel.app/reference

The main router component that renders the appropriate UI based on the current URL path and the configured routes.

```APIDOC
## `<Router />`

### Description
The component that renders the current route. This component will automatically render the component that matches the current URL path. It uses the routes configuration provided to `createRouter()` to determine which component to render.
```

--------------------------------

### Programmatic Route Preloading

Source: https://sv-router.vercel.app/guide/code-based/preloading

Use the `preload` function to programmatically trigger route preloading. Ensure the `preload` function is imported from the router.

```typescript
import { preload } from './router';

await preload('/about');
```

--------------------------------

### Accessing Dynamic Route Parameters in Svelte

Source: https://sv-router.vercel.app/guide/file-based/dynamic-routes

Demonstrates how to access dynamic route parameters using `route.getParams` (strict) and `route.params` (non-strict) within a Svelte component.

```svelte
<script lang="ts">
	import { route } from 'sv-router/generated';

	// Typed as { id: string, postId: string }
	route.getParams('/user/:id/post/:postId');

	// Typed as { id?: string, postId?: string, ... }
	route.params;
</script>
```

--------------------------------

### Importing Generated Router Exports

Source: https://sv-router.vercel.app/guide/file-based/route-definition

Access generated router exports like 'navigate' from the 'sv-router/generated' entry point. This is used throughout your application for navigation and route management.

```typescript
import { navigate, ... } from 'sv-router/generated';
```

--------------------------------

### blockNavigation(callback)

Source: https://sv-router.vercel.app/reference/index

Registers a callback to block or allow navigation based on certain conditions. This is useful for preventing accidental data loss or confirming user intent before leaving a page.

```APIDOC
## blockNavigation(callback)

### Description
Blocks navigation as long as the callback returns `false`.

### Parameters
* `callback` - Either: 
  * A function `() => boolean | Promise<boolean>` that returns `true` to allow navigation or `false` to block it. Can be async.
  * An object with: 
    * `beforeUnload?()` - (Optional) Synchronous function called on tab close/refresh. Returns `false` to prevent unloading. If not provided, tab close is not blocked.
    * `onNavigate()` - Function called on in-app navigation. Returns `boolean | Promise<boolean>`, `true` to allow, `false` to block. Can be async.

### Returns
A cleanup function that removes the blocker.

NOTE
Multiple blockers can be registered simultaneously. Navigation is blocked if any blocker returns `false`.
```

--------------------------------

### Hooks Configuration

Source: https://sv-router.vercel.app/reference/index

Configuration object for route lifecycle hooks. These functions allow you to execute logic at different stages of the route lifecycle.

```APIDOC
## Hooks Configuration

### Description
Configuration object for route lifecycle hooks.

### Properties
- `beforeLoad?(context): void | Promise<void>` - A function called before the route is loaded. You can throw a `navigate` call to redirect.
- `afterLoad?(context): void | Promise<void>` - A function called after the route is loaded.
- `onPreload?(context): void | Promise<void>` - A function called when the route is preloaded.
- `onError?(error, context): void | Promise<void>` - A function called when route components fail to load or beforeLoad hooks throw an error.

### Context Parameter
All hook functions receive a context object with the following properties:
- `pathname` - The current pathname
- `replace` - Whether this is a replace navigation (optional)
- `search` - The query string (optional)
- `state` - The history state (optional)
- `hash` - The URL hash fragment (optional)
- `meta` - The meta data
```

--------------------------------

### Configure Vite Plugin

Source: https://sv-router.vercel.app/guide/file-based/configuration

Pass an options object to the `router()` function in your Vite configuration file (`vite.config.ts`).

```typescript
import { router } from 'sv-router/vite-plugin';

export default defineConfig({
	plugins: [
		svelte(),
		router({
			path: 'src/pages',
		}),
	],
});
```

--------------------------------

### blockNavigation(callback)

Source: https://sv-router.vercel.app/reference

Blocks navigation as long as the provided callback returns `false`. This can be used to prevent accidental navigation away from unsaved changes.

```APIDOC
## blockNavigation(callback)

### Description
Blocks navigation as long as the callback returns `false`.

### Parameters
* `callback` - Either: 
    * A function `() => boolean | Promise<boolean>` that returns `true` to allow navigation or `false` to block it. Can be async.
    * An object with: 
      * `beforeUnload?()` - (Optional) Synchronous function called on tab close/refresh. Returns `false` to prevent unloading. If not provided, tab close is not blocked.
      * `onNavigate()` - Function called on in-app navigation. Returns `boolean | Promise<boolean>`, `true` to allow, `false` to block. Can be async.

### Returns
A cleanup function that removes the blocker.

NOTE
Multiple blockers can be registered simultaneously. Navigation is blocked if any blocker returns `false`.
```

--------------------------------

### Hooks Configuration

Source: https://sv-router.vercel.app/reference

Configuration object for route lifecycle hooks. These functions allow you to execute logic at various stages of the route lifecycle.

```APIDOC
## Hooks Configuration

### Description
Configuration object for route lifecycle hooks.

### Properties
* `beforeLoad?(context): void | Promise<void>` - A function called before the route is loaded. You can throw a `navigate` call to redirect.
* `afterLoad?(context): void | Promise<void>` - A function called after the route is loaded.
* `onPreload?(context): void | Promise<void>` - A function called when the route is preloaded.
* `onError?(error, context): void | Promise<void>` - A function called when route components fail to load or beforeLoad hooks throw an error.

### Context Parameter
All hook functions receive a context object with the following properties:
* `pathname` - The current pathname
* `replace` - Whether this is a replace navigation (optional)
* `search` - The query string (optional)
* `state` - The history state (optional)
* `hash` - The URL hash fragment (optional)
* `meta` - The meta data
```

--------------------------------

### Router Component

Source: https://sv-router.vercel.app/reference/index

The main Router component that renders the appropriate view based on the current URL path. It utilizes the routes configuration provided during router initialization.

```APIDOC
## <Router />

### Description
The component that renders the current route.
This component will automatically render the component that matches the current URL path. It uses the routes configuration provided to `createRouter()` to determine which component to render.
```

--------------------------------

### Define a Named Catch-All Route

Source: https://sv-router.vercel.app/guide/code-based/catch-all-routes

Optionally name the catch-all parameter (e.g., `*notfound`) to access the unmatched part of the URL via `route.params`. This provides more flexibility in handling specific unmatched segments.

```typescript
'*notfound': NotFound,

```

--------------------------------

### Define Dynamic Routes

Source: https://sv-router.vercel.app/guide/code-based/dynamic-routes

Prefix route segments with a colon to create dynamic routes that match any value. Multiple dynamic segments can be included.

```typescript
'/user/:id': User,
'/user/:id/post/:postId': Post,
```

```typescript
'/user': {
  '/:id': {
    '/': User,
    post: {
      '/:postId': Post,
    },
  },
}
```

--------------------------------

### Preventing Route Loading with beforeLoad Hook

Source: https://sv-router.vercel.app/guide/code-based/hooks

Demonstrates how to use the `beforeLoad` hook to perform an asynchronous check and prevent route loading by throwing an error. If the user is not an admin, it throws a `navigate` function to redirect to the login page.

```typescript
hooks: {
	async beforeLoad() {
		const user = await someAsyncFunction();
		if (!user.admin) {
			throw navigate('/login');
		}
	},
};
```

--------------------------------

### Navigating Browser History

Source: https://sv-router.vercel.app/guide/code-based/navigation

Utilize the `navigate` function to traverse browser history, similar to the native History API.

```typescript
// Go back one page (equivalent to the browser's back button)
navigate(-1);

// Go forward one page (equivalent to the browser's forward button)
navigate(1);

// Go back two pages
navigate(-2);
```

--------------------------------

### Preload on Link Hover

Source: https://sv-router.vercel.app/guide/code-based/preloading

Add the `data-preload` attribute to links to enable preloading when users hover over them. This works with Svelte components.

```svelte
<a href={p('/about')} data-preload>About</a>
```

--------------------------------

### Set Basename for Subpath Hosting

Source: https://sv-router.vercel.app/guide/code-based/basename

Specify the 'base' prop on the Router component to prepend a path segment to all route URLs when your app is not at the root of a domain.

```svelte
<script lang="ts">
	import { Router } from 'sv-router';
</script>

<Router base="my-app" />
```

--------------------------------

### Blocking Navigation with beforeLoad Hook Context

Source: https://sv-router.vercel.app/guide/code-based/hooks

Shows how to use the context object within the `beforeLoad` hook to conditionally block navigation. If the user is not an admin and the pathname is not '/', it throws a `navigate` function to redirect to the root path.

```typescript
hooks: {
	beforeLoad({ pathname, search, hash, state, replace, meta }) {
   if (!admin && pathname !== "/") {
         throw navigate("/");
       }
	},
};
```

--------------------------------

### Awaiting Navigation Completion

Source: https://sv-router.vercel.app/guide/code-based/navigation

Await the promise returned by `navigate` to perform actions after navigation is complete, including redirects and code splitting.

```typescript
await navigate('/dashboard');
// The navigation is complete, including any redirects or code splitting
```

--------------------------------

### Extend TypeScript Configuration

Source: https://sv-router.vercel.app/guide/file-based/manual-setup

Extend your project's TypeScript configuration from the generated `tsconfig.json` file located in the `.router` directory. This ensures TypeScript recognizes the auto-generated routes.

```json
{
	"extends": ["./.router/tsconfig.json"]
}
```

--------------------------------

### Define Route Layouts

Source: https://sv-router.vercel.app/guide/code-based/layouts

Assign a layout component to a route group to wrap its children. The layout component must render its children using `{@render children()}`.

```typescript
import About from './routes/about';
import Work from './routes/about/work';
import Team from './routes/about/team';
import AboutLayout from './routes/about/layout.svelte';

export const routes = {
	'/about': {
		'/': About,
		'/work': Work,
		'/team': Team,
		layout: AboutLayout,
	},
};
```

--------------------------------

### Ignore .router Directory in .gitignore

Source: https://sv-router.vercel.app/guide/file-based/manual-setup

Add the `.router` directory to your `.gitignore` file to prevent generated route files from being committed to version control.

```plaintext
.router
```

--------------------------------

### Customizing Active Link Classes

Source: https://sv-router.vercel.app/guide/file-based/active-route

The `className` option supports multiple space-separated classes or can be used with libraries like `clsx` for conditional class application.

```svelte
<a {@attach isActiveLink({ className: 'active highlighted' })}>About</a>
```

```svelte
<a {@attach isActiveLink({ className: clsx('active', isSpecial && 'special') })}>About</a>
```

--------------------------------

### isActiveLink

Source: https://sv-router.vercel.app/reference/index

A Svelte attachment that dynamically adds a CSS class to anchor elements when their `href` attribute matches the current route, providing visual feedback for active links.

```APIDOC
## isActiveLink

### Description
A Svelte attachment that adds a class to anchors when their `href` matches the current route.

### Parameters
* `options` - (Optional) Configuration object 
  * `className` - The class to add when active (defaults to `is-active`)
  * `startsWith` - Whether to match the start of the path (defaults to `false`)
```

--------------------------------

### Svelte Layout Component

Source: https://sv-router.vercel.app/guide/code-based/layouts

A basic Svelte component structure for a layout. It receives children as a prop and renders them.

```svelte
<script lang="ts">
	import type { Snippet } from 'svelte';

	let { children }: { children: Snippet } = $props();
</script>

<div class="wrapper">
	{@render children()}
</div>
```

--------------------------------

### searchParams Variable

Source: https://sv-router.vercel.app/reference

A reactive object that mirrors the URL's search parameters, allowing for two-way binding and automatic URL updates when changed.

```APIDOC
## `searchParams`

### Description
A reactive URL search parameters object that updates the URL when changed.

### Properties and Methods
* All standard `URLSearchParams` methods (`get`, `set`, `has`, `delete`, etc.) 
    * `options` - (Optional) For `append`, `delete`, `set` and `sort`
      * `replace` - Wheter to create a new entry in the history stack (defaults to `false`)
```

--------------------------------

### Typing Custom Route Metadata

Source: https://sv-router.vercel.app/guide/code-based/route-metadata

Customize the type of route metadata for improved type safety by augmenting the `RouteMeta` interface within the `sv-router` module.

```typescript
declare module 'sv-router' {
	interface RouteMeta {
		public?: boolean;
		requiresAuth?: boolean;
		section?: string;
	}
}
```

--------------------------------

### searchParams

Source: https://sv-router.vercel.app/reference/index

A reactive object representing the URL's search parameters. Changes to this object automatically update the URL, and vice versa, facilitating dynamic filtering and state management.

```APIDOC
## searchParams

### Description
A reactive URL search parameters object that updates the URL when changed.

### Properties and Methods
* All standard `URLSearchParams` methods (`get`, `set`, `has`, `delete`, etc.) 
  * `options` - (Optional) For `append`, `delete`, `set` and `sort`
    * `replace` - Wheter to create a new entry in the history stack (defaults to `false`)
```

--------------------------------

### Programmatically Check Active Route

Source: https://sv-router.vercel.app/guide/file-based/active-route

Use the `isActive` function for programmatic route checking with auto-complete and type safety. Supports exact matching, parameter matching, and prefix matching.

```typescript
import { isActive } from 'sv-router/generated';

// Returns true when on '/about'
isActive('/about');

// Returns true when on '/post/123'
isActive('/post/:slug', { slug: '123' });

// Returns true when on '/post/*'
isActive('/post/:slug');

// Returns true when on '/about' or '/about/*'
isActive.startsWith('/about');
```

--------------------------------

### Configure TypeScript Paths with sv-router Alias

Source: https://sv-router.vercel.app/guide/file-based/manual-setup

If using path aliases in your `tsconfig.json`, ensure you include the `sv-router/generated` alias to correctly resolve generated route files. This prevents overrides from the extended configuration.

```json
{
	"extends": ["./.router/tsconfig.json"],
	"compilerOptions": {
		"paths": {
			"your-path": ["./src/your-path"],
			"sv-router/generated": ["./.router/generated"]
		}
	}
}
```

--------------------------------

### isActiveLink

Source: https://sv-router.vercel.app/reference

A Svelte attachment that adds a class to anchor elements when their `href` attribute matches the current route, providing visual feedback for active links.

```APIDOC
## isActiveLink

### Description
A Svelte attachment that adds a class to anchors when their `href` matches the current route.

### Parameters
* `options` - (Optional) Configuration object 
    * `className` - The class to add when active (defaults to `is-active`)
    * `startsWith` - Whether to match the start of the path (defaults to `false`)
```

--------------------------------

### Blocking Navigation with Unsaved Changes

Source: https://sv-router.vercel.app/guide/code-based/navigation

Prevent users from leaving a page with unsaved changes using `blockNavigation`. It returns a cleanup function to remove the blocker.

```svelte
<script lang="ts">
	import { blockNavigation } from 'sv-router';

	let hasUnsavedChanges = $state(false);

	$effect(() =>
		blockNavigation(() => {
			if (!hasUnsavedChanges) return true;
			return confirm('You have unsaved changes. Leave anyway?');
		}),
	);
</script>
```

--------------------------------

### isActive(path, params?)

Source: https://sv-router.vercel.app/reference/index

Checks if a given route path is currently the active route in the application. It can optionally take parameters for precise matching.

```APIDOC
## isActive(path, params?)

### Description
Checks if a given path is currently active.

### Parameters
* `path` - The route to check
* `params` - (Optional) Parameters to substitute in the path

### Returns
Boolean indicating if the route is active

### Methods
* `startsWith(path: string, params?: Record<string, string | number>): boolean` - Returns true if the current route starts with the given path and parameters.
```

--------------------------------

### Control Scroll To Top with Anchor Tags

Source: https://sv-router.vercel.app/guide/code-based/scroll-behavior

Use the `data-scroll-to-top` attribute on standard anchor tags to control scroll behavior for link-based navigation. Values mirror the `scrollToTop` option for programmatic navigation.

```svelte
<!-- Default behavior - scroll to top instantly -->
<a href={p('/about')}>About</a>

<!-- Scroll to top with smooth animation -->
<a href={p('/about')} data-scroll-to-top="smooth">About</a>

<!-- Prevent scrolling to top -->
<a href={p('/about')} data-scroll-to-top="false">About</a>
```
Tokens:
Raw