react-router-breadcrumbs-hoc

React Router Breadcrumbs HOC

A tiny (~2kb minified), flexible, higher order component for rendering breadcrumbs with react-router 4.x

site.com/user/id → Home / User / John Doe

Description

Deconstruct a route and return matching breadcrumb components you can render however you like. Render a simple string, a component that fetches a model in order to display the desired content, or just render something totally unrelated to the route.

Install

yarn add react-router-breadcrumbs-hoc

or

npm install react-router-breadcrumbs-hoc --save

Usage

withBreadcrumbs()(MyComponent);

Examples

Start seeing generated breadcrumbs right away with this simple example

import withBreadcrumbs from 'react-router-breadcrumbs-hoc';

const Breadcrumbs = ({ breadcrumbs }) => (
  <React.Fragment>
    {breadcrumbs.map(({ breadcrumb }) => breadcrumb)}
  </React.Fragment>
)

export default withBreadcrumbs()(Breadcrumbs);

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 withBreadcrumbs from 'react-router-breadcrumbs-hoc';

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' },
];

// map & render your breadcrumb components however you want.
const Breadcrumbs = ({ breadcrumbs }) => (
  <div>
    {breadcrumbs.map(({
      match,
      breadcrumb
      // other props are available during render, such as `location` 
      // and any props found in your route objects will be passed through too
    }) => (
      <span key={match.url}>
        <NavLink to={match.url}>{breadcrumb}</NavLink>
      </span>
    ))}
  </div>
);

export default withBreadcrumbs(routes)(Breadcrumbs);

For the above example...

Pathname	Result
/users	Home / Users
/users/1	Home / Users / John
/example	Home / Custom Example

Already using a route config array with react-router?

Just add a breadcrumb prop to your routes that require custom breadcrumbs.

{ path, component } -> { path, component, breadcrumb }

withBreadcrumbs(routeConfig)(MyComponent)

Disabling default generated breadcrumbs

This package will attempt to create breadcrumbs for you based on the route section via humanize-string. For example /users will auotmatically 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

withBreadcrumbs(routes, { disableDefaults: true })

Option 2: Disable individual default breadcrumbs by passing breadcrumb: null in route config:

{ path: '/a/b', breadcrumb: null }

Option 3: Disable individual default breadcrumbs by passing an excludePaths array in the options object

withBreadcrumbs(routes, { excludePaths: ['/', '/no-breadcrumb/for-this-route'] })

Dynamic breadcrumbs

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:

// UserBreadcrumb.jsx
const PureUserBreadcrumb = ({ firstName }) => <span>{firstName}</span>;

// 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

---

Similarly, the location object could be useful for displaying dynamic breadcrumbs based on the route's state:

// dynamically update EditorBreadcrumb based on state info
const EditorBreadcrumb = ({ location: { state: { isNew } } }) => (
  <span>{isNew ? 'Add New' : 'Update'}</span>
);

// routes = [{ path: '/editor', breadcrumb: EditorBreadcrumb }]

// upon navigation, breadcrumb will display: Update
<Link to={{ pathname: '/editor' }}>Edit</Link>

// upon navigation, breadcrumb will display: Add New
<Link to={{ pathname: '/editor', state: { isNew: true } }}>Add</Link>

Order matters!

Consider the following route configs:

[
  { path: '/users/:id', breadcrumb: 'id-breadcrumb' },
  { path: '/users/create', breadcrumb: 'create-breadcrumb' },
]

// example.com/users/create = 'id-breadcrumb' (because path: '/users/:id' will match first)
// example.com/users/123 = 'id-breadcumb'

To fix the issue above, just adjust the order of your routes:

[
  { path: '/users/create', breadcrumb: 'create-breadcrumb' },
  { path: '/users/:id', breadcrumb: 'id-breadcrumb' },
]

// example.com/users/create = 'create-breadcrumb' (because path: '/users/create' will match first)
// example.com/users/123 = 'id-breadcrumb'

API

Route = {
  path: String
  breadcrumb: String|Function? // if not provided, a default breadcrumb will be returned
  matchOptions?: {             // see: https://reacttraining.com/react-router/web/api/matchPath
    exact?: Boolean,
    strict?: Boolean,
  }
}

Options = {
  excludePaths: Array       // disable default breadcrumb generation for specific paths
  disableDefaults: Boolean  // disable all default breadcrumb generation
}

// if routes are not passed, default breadcrumbs will be returned
withBreadcrumbs(routes?: Array<Route>, options? Object<Options>): HigherOrderComponent

// you shouldn't ever really have to use `getBreadcrumbs`, but it's
// exported for convenience if you don't want to use the HOC
getBreadcrumbs({
  routes: Array<Route>,
  options: Object<Options>,
}): Array<Breadcrumb>