mdcms/sample-sites/velox-docs/pages/api-router.md

title	sort	section-id	keywords	description	language
Router API	100	api-reference	router, useRouter, navigate, Link, createRouter, programmatic navigation	Complete API reference for the Velox router — createRouter, useRouter, navigate, and Link	en

Router API

The Velox router provides both declarative and programmatic navigation. This page documents the full public API surface of @velox/router.

useRouter()

The useRouter hook returns the current router instance. It is available inside any client-side component:

import { useRouter } from 'velox/client';

const router = useRouter();

Router Instance Properties

Property	Type	Description
pathname	string	Current URL pathname, e.g. /blog/my-post
search	string	Current query string including ?, e.g. ?page=2
hash	string	Current hash fragment including #
params	Record<string, string>	Dynamic route parameters
query	URLSearchParams	Parsed query parameters
state	unknown	History state object (if provided to navigate)

Router Instance Methods

navigate(href, options?)

Performs client-side navigation to the given href:

router.navigate('/dashboard');

// With options:
router.navigate('/profile/edit', {
  replace: true,           // replace current history entry
  state: { from: '/dashboard' }, // pass arbitrary state
  scroll: false,           // don't scroll to top after navigation
});

back() / forward()

Navigate through the browser history stack:

router.back();
router.forward();

prefetch(href)

Manually prefetch a route (downloads the JS bundle and optionally data):

router.prefetch('/heavy-page');

refresh()

Re-run the current route's server block and update the page without a full navigation:

router.refresh();

<Link> Component

The <Link> component renders an accessible <a> element with client-side navigation and built-in prefetching:

import { Link } from 'velox/client';

<Link href="/about">About</Link>

Props

Prop	Type	Default	Description
href	string	required	Destination URL
prefetch	'hover' | 'viewport' | false	'hover'	Prefetch strategy
replace	boolean	false	Replace history entry instead of pushing
scroll	boolean	true	Scroll to top after navigation
state	unknown	undefined	History state object
activeClass	string	'active'	CSS class applied when href matches current pathname
exactActiveClass	string	'exact-active'	CSS class applied only on exact pathname match

<Link
  href="/blog"
  prefetch="viewport"
  activeClass="nav-link--active"
  exactActiveClass="nav-link--exact"
>
  Blog
</Link>

createRouter()

For testing or server-side use, create a router instance manually:

import { createRouter } from 'velox/router';

const router = createRouter({
  base: '/app',               // base path prefix
  history: 'hash',            // 'browser' (default) | 'hash' | 'memory'
  scrollRestoration: 'auto',  // 'auto' | 'manual'
});

useParams()

Access current route parameters in any component:

import { useParams } from 'velox/client';

const { slug, category } = useParams<{ slug: string; category: string }>();

useSearchParams()

Read and update the URL search parameters reactively:

import { useSearchParams } from 'velox/client';

const [searchParams, setSearchParams] = useSearchParams();

// Read
const page = searchParams.get('page') ?? '1';

// Update (triggers navigation without full page reload)
setSearchParams({ page: String(currentPage + 1) });

// Merge with existing params
setSearchParams(prev => {
  prev.set('sort', 'date');
  return prev;
});

usePathname()

Reactively access the current pathname:

import { usePathname } from 'velox/client';

const pathname = usePathname();
// pathname is a Signal<string>

useNavigate()

A lightweight hook that returns only the navigate function, without the full router object:

import { useNavigate } from 'velox/client';

const navigate = useNavigate();
navigate('/login');

Navigation Events

Subscribe to router lifecycle events:

import { useRouter } from 'velox/client';

const router = useRouter();

const unsubscribe = router.on('beforeNavigate', ({ to, from, cancel }) => {
  if (hasUnsavedChanges && !confirm('Leave without saving?')) {
    cancel();
  }
});

// Clean up
onCleanup(unsubscribe);

Available events: beforeNavigate, afterNavigate, navigationError.

redirect() (Server)

Used inside server blocks and API route handlers:

import { redirect } from 'velox/server';

// Temporary redirect (302)
throw redirect('/login');

// Permanent redirect (301)
throw redirect('/new-url', 301);

// With custom headers
throw redirect('/dashboard', 302, {
  'Set-Cookie': 'session=...; Path=/',
});

notFound() (Server)

Trigger the nearest _error.velox with a 404 status:

import { notFound } from 'velox/server';

const post = await db.posts.find(id);
if (!post) throw notFound();