HeliumTS is under active development and may have bugs or breaking changes. Report issues on GitHub.

useRouter Hook

Overview

The useRouter hook provides access to routing information and navigation methods.

1import { useRouter } from "heliumts/client";
2
3export default function MyComponent() {
4 const router = useRouter();
5
6 // Access router properties
7 console.log(router.path);
8 console.log(router.params);
9 console.log(router.searchParams);
10 console.log(router.status);
11
12 return <div>...</div>;
13}

Properties

path (string)

Current pathname (without query string):

1const router = useRouter();
2console.log(router.path); // "/blog/my-post"

params (Record<string, string | string[]>)

Dynamic route parameters:

1// URL: /users/123
2const router = useRouter();
3console.log(router.params.id); // "123"
4
5// URL: /docs/guide/getting-started (catch-all route)
6const router = useRouter();
7console.log(router.params.slug); // ["guide", "getting-started"]

searchParams (URLSearchParams)

URL query parameters:

1// URL: /search?q=hello&page=2
2const router = useRouter();
3console.log(router.searchParams.get("q")); // "hello"
4console.log(router.searchParams.get("page")); // "2"
5
6// Get all values as object
7const allParams = Object.fromEntries(router.searchParams);
8console.log(allParams); // { q: "hello", page: "2" }

status (200 | 404)

Current route status:

1const router = useRouter();
2
3if (router.status === 404) {
4 return <div>Page not found</div>;
5}
6
7return <div>Content</div>;

isNavigating (boolean)

Indicates whether a navigation is currently in progress. Useful for showing loading indicators:

1const router = useRouter();
2
3return (
4 <div>
5 {router.isNavigating && <LoadingSpinner />}
6 <main>{/* page content */}</main>
7 </div>
8);

isPending (boolean)

Indicates when content is stale (React 18+ concurrent feature). True when React is rendering a new page in the background while still showing old content:

1const router = useRouter();
2
3return (
4 <div style={{ opacity: router.isPending ? 0.7 : 1 }}>
5 <main>{/* page content */}</main>
6 </div>
7);

Methods

push(href: string)

Navigate to a new route (adds to history):

1const router = useRouter();
2
3router.push("/about");
4router.push("/users/123");
5router.push("/search?q=hello");

replace(href: string)

Navigate to a new route (replaces current history entry):

1const router = useRouter();
2
3// Replace current URL (no back button entry)
4router.replace("/login");

on(event, listener)

Subscribe to router events. Returns an unsubscribe function:

1const router = useRouter();
2
3useEffect(() => {
4 // Listen to navigation events
5 const unsubscribe = router.on("navigation", (event) => {
6 console.log(`Navigated from ${event.from} to ${event.to}`);
7 });
8
9 // Cleanup
10 return unsubscribe;
11}, [router]);

Router Events

Event Types

  • "navigation": Fires after navigation completes
  • "before-navigation": Fires before navigation (can be prevented)

Event Object

1{
2 from: string; // Previous path
3 to: string; // New path
4 preventDefault?: () => void; // Only for "before-navigation"
5}

Fires after navigation completes:

1import { useRouter } from "heliumts/client";
2import { useEffect } from "react";
3
4export default function Analytics() {
5 const router = useRouter();
6
7 useEffect(() => {
8 const unsubscribe = router.on("navigation", (event) => {
9 // Track page view
10 trackPageView(event.to);
11 });
12
13 return unsubscribe;
14 }, [router]);
15
16 return null;
17}

Before Navigation Event

Fires before navigation and can be prevented:

1import { useRouter } from "heliumts/client";
2import { useEffect, useState } from "react";
3
4export default function UnsavedChangesGuard() {
5 const router = useRouter();
6 const [hasUnsavedChanges, setHasUnsavedChanges] = useState(false);
7
8 useEffect(() => {
9 const unsubscribe = router.on("before-navigation", (event) => {
10 if (hasUnsavedChanges) {
11 const confirmed = window.confirm(
12 "You have unsaved changes. Do you want to leave?"
13 );
14
15 if (!confirmed) {
16 event.preventDefault?.(); // Prevent navigation
17 }
18 }
19 });
20
21 return unsubscribe;
22 }, [router, hasUnsavedChanges]);
23
24 return <form>...</form>;
25}

TypeScript Support

Typing Route Params

1import { useRouter } from "heliumts/client";
2
3type UserPageParams = {
4 id: string;
5};
6
7export default function UserPage() {
8 const router = useRouter();
9 const { id } = router.params as UserPageParams;
10
11 // id is typed as string
12 return <div>User: {id}</div>;
13}

Typing Search Params

1import { useRouter } from "heliumts/client";
2
3export default function SearchPage() {
4 const router = useRouter();
5
6 const query = router.searchParams.get("q") ?? "";
7 const page = Number(router.searchParams.get("page") ?? "1");
8
9 // query: string, page: number
10 return <div>Search: {query}, Page: {page}</div>;
11}

Troubleshooting

useRouter throws "must be used inside <AppRouter>"

Cause: useRouter called outside the router context

Solution: Ensure you deleted /src/main.tsx and your /src/App.tsx is like this:

1import { type AppShellProps } from "heliumts/client";
2
3export default function App({ Component, pageProps }: AppShellProps) {
4 return <Component {...pageProps} />;
5}

Dynamic params are undefined

Cause: Wrong param name or file structure

Solution: Ensure param name matches filename:

  • File: [id].tsx → Param: router.params.id
  • File: [slug].tsx → Param: router.params.slug