Usage

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

useRouter should 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'
// }

Note on TypeScript: 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';