Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/icd2k3/use-react-router-breadcrumbs
tiny, flexible, hook for rendering route breadcrumbs with react-router v6
https://github.com/icd2k3/use-react-router-breadcrumbs
breadcrumbs hook react react-router router
Last synced: 4 days ago
JSON representation
tiny, flexible, hook for rendering route breadcrumbs with react-router v6
- Host: GitHub
- URL: https://github.com/icd2k3/use-react-router-breadcrumbs
- Owner: icd2k3
- License: mit
- Created: 2020-03-26T15:29:39.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2023-07-19T22:46:31.000Z (over 1 year ago)
- Last Synced: 2025-01-27T08:07:05.419Z (11 days ago)
- Topics: breadcrumbs, hook, react, react-router, router
- Language: TypeScript
- Homepage: https://stackblitz.com/edit/github-fiw8uj?file=src/App.tsx
- Size: 2.92 MB
- Stars: 261
- Watchers: 4
- Forks: 23
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
---
# Important
As of `react-router v6.4` there is an [officially supported way](https://reactrouter.com/en/main/hooks/use-matches#breadcrumbs) of producing breadcrumbs. I recommend using this approach, but if it doesn't cover your specific use case, please let us know in the issues.
---
---
---
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](#description)
- [Features](#features)
- [Install](#install)
- [Usage](#usage)
- [Examples](#examples)
- [Simple](#simple)
- [Advanced](#advanced)
- [Route config compatibility](#route-config-compatibility)
- [Dynamic breadcrumb components](#dynamic-breadcrumb-components)
- [Options](#options)
- [Disabling default generated breadcrumbs](#disabling-default-generated-breadcrumbs)
- [Order matters!](#order-matters)
- [API](#api)
## 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](https://github.com/remix-run/react-router/tree/main/examples/route-objects).
## Install
`yarn add use-react-router-breadcrumbs`
or
`npm i use-react-router-breadcrumbs --save`
## Usage
```js
const breadcrumbs = useBreadcrumbs();
```
## Examples
### Simple
Start seeing generated breadcrumbs right away with this simple example
```js
import useBreadcrumbs from "use-react-router-breadcrumbs";
const Breadcrumbs = () => {
const breadcrumbs = useBreadcrumbs();
return (
{breadcrumbs.map(({ breadcrumb }) => breadcrumb)}
);
};
```
### 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.
```js
import useBreadcrumbs from "use-react-router-breadcrumbs";
const userNamesById = { 1: "John" };
const DynamicUserBreadcrumb = ({ match }) => (
{userNamesById[match.params.userId]}
);
const CustomPropsBreadcrumb = ({ someProp }) => {someProp};
// define custom breadcrumbs for certain routes.
// breadcrumbs can be components or strings.
const routes = [
{ path: "/users/:userId", breadcrumb: DynamicUserBreadcrumb },
{ path: "/example", breadcrumb: "Custom Example" },
{
path: "/custom-props",
breadcrumb: CustomPropsBreadcrumb,
props: { someProp: "Hi" },
},
];
// map & render your breadcrumb components however you want.
const Breadcrumbs = () => {
const breadcrumbs = useBreadcrumbs(routes);
return (
<>
{breadcrumbs.map(({ match, breadcrumb }) => (
{breadcrumb}
))}
>
);
};
```
For the above example...
| Pathname | Result |
| ------------- | --------------------- |
| /users | Home / Users |
| /users/1 | Home / Users / John |
| /example | Home / Custom Example |
| /custom-props | Home / Hi |
### Advanced (Declarative Routes)
Same as the example above using Declarative Routing.
```js
import useBreadcrumbs, { createRoutesFromChildren, Route } from 'use-react-router-breadcrumbs';
const userNamesById = { '1': 'John' }
const DynamicUserBreadcrumb = ({ match }) => (
{userNamesById[match.params.userId]}
);
const CustomPropsBreadcrumb = ({ someProp }) => (
{someProp}
);
// define custom breadcrumbs for certain routes.
// breadcrumbs can be components or strings.
// map & render your breadcrumb components however you want.
const BreadcrumbTrail = ({ breadCrumbs }) => {
return (
<>
{breadcrumbs.map(({
match,
breadcrumb
}) => (
{breadcrumb}
))}
>
);
};
const GenerateAppRoutes = () => {
// Full declarative react router support. example: Element, children, Nested Routes
return (
} />
)
};
const AppRouter = () => {
// You could use context to set app Routes and add the breadcrumbs somewhere deeper in the application layout.
const AppRoutes = GenerateAppRoutes();
const appRouteObjects = createRoutesFromChildren(AppRoutes);
const breadCrumbs = useBreadcrumbs(appRouteObjects)
const GeneratedRoutes = useRoutes(appRouteObjects);
return (
)
}
```
For the above example...
| Pathname | Result |
| ------------- | --------------------- |
| /users | Home / Users |
| /users/1 | Home / Users / John |
| /example | Home / Custom Example |
| /custom-props | Home / Hi |
## [Route object](https://github.com/remix-run/react-router/tree/main/examples/route-objects) compatibility
Add breadcrumbs to your existing [route object](https://github.com/remix-run/react-router/tree/main/examples/route-objects). 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...
```js
const routes = [
{
path: "/sandwiches",
element: ,
},
];
```
becomes...
```js
const routes = [
{
path: "/sandwiches",
element: ,
breadcrumb: "I love sandwiches",
},
];
```
then you can just pass the whole routes right into the hook:
```js
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](https://reactrouter.com/docs/en/v6/api#matchpath) and [location](https://reactrouter.com/docs/en/v6/api#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](https://reactrouter.com/docs/en/v6/api#matchpath) object:
```js
// UserBreadcrumb.jsx
const PureUserBreadcrumb = ({ firstName }) => {firstName};
// find the user in the store with the `id` from the route
const mapStateToProps = (state, props) => ({
firstName: state.userReducer.usersById[props.match.params.id].firstName,
});
export default connect(mapStateToProps)(PureUserBreadcrumb);
// routes = [{ path: '/users/:id', breadcrumb: UserBreadcrumb }]
// example.com/users/123 --> Home / Users / John
```
Now we can pass this custom `redux` breadcrumb into the hook:
```js
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:
```tsx
import type { BreadcrumbComponentType } from "use-react-router-breadcrumbs";
const UserBreadcrumb: BreadcrumbComponentType<"id"> = ({ match }) => {
return
{match.params.id};
};
```
---
Similarly, the [location](https://reactrouter.com/docs/en/v6/api#location) object could be useful for displaying dynamic breadcrumbs based on the route's state:
```jsx
// dynamically update EditorBreadcrumb based on state info
const EditorBreadcrumb = ({ location: { state: { isNew } } }) => (
{isNew ? 'Add New' : 'Update'}
);
// routes = [{ path: '/editor', breadcrumb: EditorBreadcrumb }]
// upon navigation, breadcrumb will display: Update
Edit
// upon navigation, breadcrumb will display: Add New
Add
```
## Options
An options object can be passed as the 2nd argument to the hook.
```js
useBreadcrumbs(routes, options);
```
| Option | Type | Description |
| ----------------- | --------------- | ---------------------------------------------------------- |
| `disableDefaults` | `Boolean` | Disables all default generated breadcrumbs. |
| `excludePaths` | `Array` | 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
```js
const breadcrumbs = useBreadcrumbs(routes, { disableDefaults: true });
```
**Option 2:** Disable _individual_ default breadcrumbs by passing `breadcrumb: null` in route config:
```js
const routes = [{ path: "/a/b", breadcrumb: null }];
```
**Option 3:** Disable _individual_ default breadcrumbs by passing an `excludePaths` array in the `options` object
```js
useBreadcrumbs(routes, {
excludePaths: ["/", "/no-breadcrumb/for-this-route"],
});
```
## Order matters!
`use-react-router-breadcrumbs` uses the [same strategy](https://reactrouter.com/docs/en/v6/getting-started/concepts#ranking-routes) as `react-router 6` to calculate the routing order.
```js
[
{
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:
```js
[
{
path: "users",
breadcrumb: "parent-breadcrumb",
children: [{ index: true, breadcrumb: "child-breadcrumb" }],
},
];
```
If the user visits `example.com/users` they will see `child-breadcrumb`.
## API
```ts
interface BreadcrumbComponentProps {
key: string;
match: BreadcrumbMatch;
location: Location;
}
type BreadcrumbComponentType =
React.ComponentType>;
interface BreadcrumbsRoute
extends RouteObject {
children?: BreadcrumbsRoute[];
breadcrumb?: BreadcrumbComponentType | string | null;
props?: { [x: string]: unknown };
}
interface Options {
// disable all default generation of breadcrumbs
disableDefaults?: boolean;
// exclude certain paths fom generating breadcrumbs
excludePaths?: string[];
// optionally define a default formatter for generating breadcrumbs from URL segments
defaultFormatter?: (string) => string;
}
interface BreadcrumbData {
match: BreadcrumbMatch;
location: Location;
key: string;
breadcrumb: React.ReactNode;
}
// if routes are not passed, default breadcrumbs will be returned
function useBreadcrumbs(
routes?: BreadcrumbsRoute[],
options?: Options
): BreadcrumbData[];
```