Usage

The useRouter hook is based on the React Router Dom Libraryopens in a new window. This hook provides several methods that allow users to manage and interact with routing and navigation.

Important

useRouter must be used within the context of a RouterProvider.

import { useRouter } from '@uhg-abyss/web/hooks/useRouter';

matchPath

matchPath matches a path with a set of given parameters. The first argument is a path string. The second is a JSON object with a path variable and optional arguments. matchPath will return a JSON object if paths match or null if they do not.

const { matchPath } = useRouter();

const match = matchPath('/users/123', {
  path: '/users/:id', // either a single string or an array of strings
  exact: true, // optional, defaults to false
  strict: false, // optional, defaults to false
});

// returns object if true and null if false

//  {
//    isExact: true
//    params: {
//        id: "2"
//    }
//    path: "/users/:id"
//    url: "/users/2"
//  }

navigate

The navigate hook returns a function that lets you navigate programmatically. Below is an example of a button component that will navigate to the getting started page when clicked.

const NavigationButton = () => {
  const { navigate } = useRouter();

  return (
    <button
      onClick={() => {
        navigate('/getting-started/');
      }}
    >
      test
    </button>
  );
};

getLocation

getLocation returns a JSON object with information about current router location. It is commonly used to trigger useEffect logic when location changes.

It can return one of three values:

• React Router location object — when inside a RouterProvider context.
• Native browser location object — when outside Router context in a browser.
• null — when no location is available (for example, in server-side rendering, certain test environments, or before the router has initialized).

const { getLocation } = useRouter();
let location = getLocation();

React.useEffect(() => {
  console.log(location);
}, [location]);

// location variable Value example
// {
//   pathname: '/',
//   search: '',
//   hash: '',
//   state: null,
//   key: 'zflihx26'
// }

Tip

Due to TypeScript limitations in distinguishing between RRLocation and Location, the return type of getLocation() is any. You can manually cast the type before accessing type-specific properties like state or href.

import { useRouter } from '@uhg-abyss/web/hooks/useRouter';
import { Location as RRLocation, useInRouterContext }
  from '@uhg-abyss/web/tools/reactRouterTools';

//...

const { getLocation } = useRouter();
let location = getLocation();

let inRouterContext = false;
if (useInRouterContext) {
  inRouterContext = useInRouterContext();
}


if (inRouterContext && location) {
  const rrLoc = location as RRLocation;
  console.log('React Router location state:', rrLoc.state);
} else if (location) {
  const browserLoc = location as Location;
  console.log('Browser location href:', browserLoc.href);
} else {
  console.log('No location available (Null)');
}

getRouteParams

getRouteParams returns an object of key/value pairs of the dynamic params from the current URL. Pass a path variable to return params specific to that path.

const { getRouteParams } = useRouter();

const params = getRouteParams();
const paramsOnPath = getRouteParams('/pathExample');

getSearchParams

getSearchParams is used to read the query string in the URL for the current location and returns all search parameters.

const { getSearchParams } = useRouter();
const [searchParams] = getSearchParams();

usePathComparison

usePathComparison is not part of useRouter, but functions on similar logic. It can be used to compare a given URL with the current url. Returns true if both paths match or false if they do not

import { usePathComparison } from '../usePathComparison';

const urlIsSameAsCurrent = usePathComparison('url');

Additional documentation

Teams wanting to use React Router (v7) directly can import from this path to ensure consistent versions across your application:

import { useLocation, useParams } from '@uhg-abyss/web/tools/reactRouterTools';