use-react-router-breadcrumbs
A small (~1.25kb gzip), flexible, hook for rendering breadcrumbs with react-router 6.
example.com/user/123 → Home / User / John Doe
Using an older version of react-router
? Check out react-router-breadcrumbs-hoc which is compatible with v4 and v5.
Description
Render breadcrumbs for react-router
6 however you want!
Features
- Easy to get started with automatically generated breadcrumbs.
- Render, map, and wrap breadcrumbs any way you want.
- Compatible with existing route objects.
Install
yarn add use-react-router-breadcrumbs
or
npm i use-react-router-breadcrumbs --save
Usage
const breadcrumbs = useBreadcrumbs()
Examples
Simple
Start seeing generated breadcrumbs right away with this simple example
import useBreadcrumbs from 'use-react-router-breadcrumbs';
const Breadcrumbs = () => {
const breadcrumbs = useBreadcrumbs();
return (
<React.Fragment>
{breadcrumbs.map(({ breadcrumb }) => breadcrumb)}
</React.Fragment>
);
}
Advanced
The example above will work for some routes, but you may want other routes to be dynamic (such as a user name breadcrumb). Let's modify it to handle custom-set breadcrumbs.
import useBreadcrumbs from 'use-react-router-breadcrumbs';
const userNamesById = { '1': 'John' }
const DynamicUserBreadcrumb = ({ match }) => (
<span>{userNamesById[match.params.userId]}</span>
);
const routes = [
{ path: '/users/:userId', breadcrumb: DynamicUserBreadcrumb },
{ path: '/example', breadcrumb: 'Custom Example' },
];
const Breadcrumbs = () => {
const breadcrumbs = useBreadcrumbs(routes);
return (
<>
{breadcrumbs.map(({
match,
breadcrumb
}) => (
<span key={match.pathname}>
<NavLink to={match.pathname}>{breadcrumb}</NavLink>
</span>
))}
</>
);
};
For the above example...
Pathname | Result |
---|
/users | Home / Users |
/users/1 | Home / Users / John |
/example | Home / Custom Example |
Add breadcrumbs to your existing route object. This is a great way to keep all routing config paths in a single place! If a path ever changes, you'll only have to change it in your main route config rather than maintaining a separate config for use-react-router-breadcrumbs
.
For example...
const routes = [
{
path: "/sandwiches",
element: <Sandwiches />
}
];
becomes...
const routes = [
{
path: "/sandwiches",
element: <Sandwiches />,
breadcrumb: 'I love sandwiches'
}
];
then you can just pass the whole routes right into the hook:
const breadcrumbs = useBreadcrumbs(routes);
Dynamic breadcrumb components
If you pass a component as the breadcrumb
prop it will be injected with react-router's match and location objects as props. These objects contain ids, hashes, queries, etc... from the route that will allow you to map back to whatever you want to display in the breadcrumb.
Let's use redux
as an example with the match object:
const PureUserBreadcrumb = ({ firstName }) => <span>{firstName}</span>;
const mapStateToProps = (state, props) => ({
firstName: state.userReducer.usersById[props.match.params.id].firstName,
});
export default connect(mapStateToProps)(PureUserBreadcrumb);
Now we can pass this custom redux
breadcrumb into the hook:
const breadcrumbs = useBreadcrumbs([{
path: '/users/:id',
breadcrumb: UserBreadcrumb
}]);
You cannot use hooks that rely on RouteContext
like useParams
, because the breadcrumbs are not in the context, you should use match.params
instead:
import type { BreadcrumbComponentType } from 'use-react-router-breadcrumbs';
const UserBreadcrumb: BreadcrumbComponentType<'id'> = ({ match }) => {
return <div>{match.params.id}</div>;
}
Similarly, the location object could be useful for displaying dynamic breadcrumbs based on the route's state:
const EditorBreadcrumb = ({ location: { state: { isNew } } }) => (
<span>{isNew ? 'Add New' : 'Update'}</span>
);
<Link to={{ pathname: '/editor' }}>Edit</Link>
<Link to={{ pathname: '/editor', state: { isNew: true } }}>Add</Link>
Options
An options object can be passed as the 2nd argument to the hook.
useBreadcrumbs(routes, options);
Option | Type | Description |
---|
disableDefaults | Boolean | Disables all default generated breadcrumbs. |
excludePaths | Array<String> | Disables default generated breadcrumbs for specific paths. |
Disabling default generated breadcrumbs
This package will attempt to create breadcrumbs for you based on the route section. For example /users
will automatically create the breadcrumb "Users"
. There are two ways to disable default breadcrumbs for a path:
Option 1: Disable all default breadcrumb generation by passing disableDefaults: true
in the options
object
const breadcrumbs = useBreadcrumbs(routes, { disableDefaults: true })
Option 2: Disable individual default breadcrumbs by passing breadcrumb: null
in route config:
const routes = [{ path: '/a/b', breadcrumb: null }];
Option 3: Disable individual default breadcrumbs by passing an excludePaths
array in the options
object
useBreadcrumbs(routes, { excludePaths: ['/', '/no-breadcrumb/for-this-route'] })
Order matters!
use-react-router-breadcrumbs
uses the same strategy as react-router 6
to calculate the routing order.
[
{
path: 'users',
children: [
{ path: ':id', breadcrumb: 'id-breadcrumb' },
{ path: 'create', breadcrumb: 'create-breadcrumb' },
],
},
]
If the user visits example.com/users/create
they will see create-breadcrumb
.
In addition, if the index route and the parent route provide breadcrumb at the same time, the index route provided will be used first:
[
{
path: 'users',
breadcrumb: 'parent-breadcrumb',
children: [
{ index: true, breadcrumb: 'child-breadcrumb' },
],
},
]
If the user visits example.com/users
they will see child-breadcrumb
.
API
interface BreadcrumbComponentProps<ParamKey extends string = string> {
key: string;
match: BreadcrumbMatch<ParamKey>;
location: Location;
}
type BreadcrumbComponentType<ParamKey extends string = string> =
React.ComponentType<BreadcrumbComponentProps<ParamKey>>;
interface BreadcrumbsRoute<ParamKey extends string = string>
extends RouteObject {
children?: BreadcrumbsRoute[];
breadcrumb?: BreadcrumbComponentType<ParamKey> | string | null;
props?: { [x: string]: unknown };
}
interface Options {
disableDefaults?: boolean;
excludePaths?: string[];
}
interface BreadcrumbData<ParamKey extends string = string> {
match: BreadcrumbMatch<ParamKey>;
location: Location;
key: string;
breadcrumb: React.ReactNode;
}
function useBreadcrumbs(
routes?: BreadcrumbsRoute[],
options?: Options
): BreadcrumbData[];