diff --git a/.travis.yml b/.travis.yml
index 8bba685..96d9d98 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -2,7 +2,7 @@ language: node_js
node_js:
- "8.9.0"
before_install:
- - curl -o- -L https://yarnpkg.com/install.sh | bash -s -- --version 1.3.2
+ - curl -o- -L https://yarnpkg.com/install.sh | bash -s -- --version 1.5.1
- export PATH="$HOME/.yarn/bin:$PATH"
script:
- yarn run travis
diff --git a/MIGRATIONS.md b/MIGRATIONS.md
new file mode 100644
index 0000000..eced28c
--- /dev/null
+++ b/MIGRATIONS.md
@@ -0,0 +1,52 @@
+## Migrating from 1.x.x -> 2.x.x
+
+> 1.) `withBreadcrumbs` is now the default export
+
+_1.x.x_
+```js
+import { withBreadcrumbs } from 'react-router-breadcrumbs-hoc';
+```
+
+_2.x.x_
+```js
+import withBreadcrumbs from 'react-router-breadcrumbs-hoc';
+```
+
+> 2.) The breadcrumbs array returned by the HOC is now _just_ the components. It _used_ to be an array of objects, but I decided this approach was easier to understand and made the implementation code a bit cleaner.
+
+_1.x.x_
+```js
+{breadcrumbs.map(({ breadcrumb, path, match }) => (
+
+
+ {breadcrumb}
+
+
+))}
+```
+
+_2.x.x_
+```js
+{breadcrumbs.map(breadcrumb => (
+
+
+ {breadcrumb}
+
+
+))}
+```
+
+> 3.) The package will now attempt to return sensible defaults for breadcrumbs unless otherwise provided making the the package now "opt-out" instead of "opt-in" for all paths. See the readme for how to disable default breadcrumb behavior.
+
+_1.x.x_
+```js
+withBreadcrumbs([
+ { path: '/', breadcrumb: 'Home' },
+ { path: '/users', breadcrumb: 'Users' },
+])(Component);
+```
+
+_2.x.x_ (the above breadcrumbs will be automagically generated so there's no need to include them in config)
+```js
+withBreadcrumbs()(Component);
+```
diff --git a/README.md b/README.md
index b4b5d71..d1e3b79 100644
--- a/README.md
+++ b/README.md
@@ -3,11 +3,11 @@
- Just a tiny, flexible, higher order component for rendering breadcrumbs with react-router 4.x
+ A tiny (~2kb minified), flexible, higher order component for rendering breadcrumbs with react-router 4.x
- site.com/user/id → user / John Doe
+ site.com/user/id → Home / User / John Doe
@@ -34,35 +34,36 @@ or
## Usage
```js
-withBreadcrumbs(routeConfigObject)(MyComponent);
+withBreadcrumbs()(MyComponent);
```
-## Example
+## Simple example
```js
import React from 'react';
import { NavLink } from 'react-router-dom';
-import { withBreadcrumbs } from 'react-router-breadcrumbs-hoc';
+import withBreadcrumbs from 'react-router-breadcrumbs-hoc';
+// breadcrumbs can be any type of component or string
const UserBreadcrumb = ({ match }) =>
{match.params.userId} ; // use match param userId to fetch/display user name
+// define some custom breadcrumbs for certain routes (optional)
const routes = [
- { path: '/', breadcrumb: 'Home' },
- { path: '/users', breadcrumb: 'Users' },
{ path: '/users/:userId', breadcrumb: UserBreadcrumb },
- { path: '/something-else', breadcrumb: ':)' },
+ { path: '/example', breadcrumb: 'Custom Example' },
];
-// map & render your breadcrumb components however you want
+// map & render your breadcrumb components however you want.
+// each `breadcrumb` has the props `key`, `location`, and `match` included!
const Breadcrumbs = ({ breadcrumbs }) => (
- {breadcrumbs.map(({ breadcrumb, path, match }) => (
-
-
+ {breadcrumbs.map((breadcrumb, index) => (
+
+
{breadcrumb}
- /
+ {(index < breadcrumbs.length - 1) && / }
))}
@@ -77,72 +78,79 @@ Pathname | Result
--- | ---
/users | Home / Users
/users/id | Home / Users / John
-/something-else | Home / :)
+/example | Home / Custom Example
+
+## Disabling default breadcrumbs for paths
+
+This package will attempt to create breadcrumbs for you based on the route section via [humanize-string](https://github.com/sindresorhus/humanize-string). For example `/users` will auotmatically create the breadcrumb `"Users"`. There are two ways to disable default breadcrumbs for a path:
+
+1.) Pass `breadcrumb: null` in the routes config
+`{ path: '/a/b', breadcrumb: null }`
+
+2.) Pass an `excludePaths` array in the `options`
+`withBreadcrumbs(routes, { excludePaths: ['/', '/no-breadcrumb/for-this-route'] })`
+
+in your routes array.
## Already using a [route config](https://reacttraining.com/react-router/web/example/route-config) array with react-router?
-Just add a `breadcrumbs` prop to your routes that require breadcrumbs!
+Just add a `breadcrumbs` prop to your routes that require custom breadcrumbs.
-> Note: currently nested `routes` arrays are not supported, but will be soon (see: https://github.com/icd2k3/react-router-breadcrumbs-hoc/issues/24)
+> Note: currently, nested `route`s arrays are _not_ supported, but will be soon (see: https://github.com/icd2k3/react-router-breadcrumbs-hoc/issues/24)
## API
```js
Route = {
path: String
- breadcrumb: String|Function
+ breadcrumb: String|Function? // note: if not provided, a default breadcrumb will be returned
matchOptions?: Object
}
-Breadcrumb = {
- path: String
- match: String
- breadcrumb: Component
+Options = {
+ excludePaths: Array
}
-// react-router's location object: https://reacttraining.com/react-router/web/api/location
-Location = {
- key: String
- pathname: String
- search: String
- hash: String
- state: Object
-}
-
-withBreadcrumbs(routes: Array): HigherOrderComponent
+// if routes are not passed, default breadcrumbs will be returned
+withBreadcrumbs(routes?: Array, options? Object): 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, location: Location }): Array
+getBreadcrumbs({
+ routes: Array,
+ location: Object, // react-router's location object: https://reacttraining.com/react-router/web/api/location
+ options: Object,
+}): Array
```
-## Order Matters!
+## Order matters!
-Consider the following route config:
+Consider the following route configs:
```js
[
- { path: '/users', breadcrumb: 'Users' },
- { path: '/users/:id', breadcrumb: 'Users - id' },
- { path: '/users/create', breadcrumb: 'Users - create' },
+ { path: '/users/:id', breadcrumb: 'id-breadcrumb' },
+ { path: '/users/create', breadcrumb: 'create-breadcrumb' },
]
-```
-This package acts like a switch statement and matches the first breadcrumb it can find. So, unfortunately, visiting `/users/create` will result in the `Users > Users - id` breadcrumbs instead of the desired `Users > Users - create` breadcrumbs.
+// example.com/users/create = 'id-breadcrumb' (because path: '/users/:id' will match first)
+// example.com/users/123 = 'id-breadcumb'
+```
-To get the right breadcrumbs, simply change the order:
+To fix the issue above, just adjust the order of your routes:
```js
[
- { path: '/users', breadcrumb: 'Users' },
- { path: '/users/create', breadcrumb: 'Users - create' },
- { path: '/users/:id', breadcrumb: 'Users - id' },
+ { 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'
```
-Now, `/users/create` will match the create breadcrumb first, and all others will fall through to `/:id`.
+## Using the location object
-## Using the Location Object
React Router's [location](https://reacttraining.com/react-router/web/api/location) object lets you pass `state` property. Using the `state` allows one to update the Breadcrumb to display dynamic info at runtime. Consider this example:
```jsx
diff --git a/jest.config.js b/jest.config.js
index 192c92a..bd31af3 100644
--- a/jest.config.js
+++ b/jest.config.js
@@ -16,5 +16,4 @@ module.exports = {
},
},
setupFiles: ['./jest.setup.js'],
- snapshotSerializers: ['enzyme-to-json/serializer'],
};
diff --git a/package.json b/package.json
index 2bd37f4..3f48cf3 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "react-router-breadcrumbs-hoc",
- "version": "1.2.0",
+ "version": "2.0.0",
"description": "Just a tiny, flexible, higher order component for rendering breadcrumbs with react-router 4.x",
"repository": "icd2k3/react-router-breadcrumbs-hoc",
"keywords": [
@@ -19,6 +19,9 @@
"react-router": "^4.2.0",
"react-router-dom": "^4.2.2"
},
+ "dependencies": {
+ "humanize-string": "^1.0.1"
+ },
"devDependencies": {
"babel-cli": "^6.26.0",
"babel-core": "^6.8.0",
@@ -30,11 +33,9 @@
"babel-preset-react": "^6.24.1",
"babel-preset-stage-1": "^6.24.1",
"coveralls": "^3.0.0",
- "cross-env": "^5.1.3",
"enzyme": "^3.2.0",
"enzyme-adapter-react-16": "^1.1.0",
- "enzyme-to-json": "^3.3.0",
- "eslint": "^4.18.1",
+ "eslint": "^4.18.2",
"eslint-config-airbnb": "^16.1.0",
"eslint-plugin-import": "^2.9.0",
"eslint-plugin-jsx-a11y": "^6.0.3",
@@ -45,16 +46,16 @@
"react-dom": "^16.2.0",
"react-router": "^4.2.0",
"react-router-dom": "^4.2.2",
- "rollup": "^0.56.3",
+ "rollup": "^0.56.5",
"rollup-plugin-babel": "^3.0.3",
- "rollup-plugin-commonjs": "^8.2.6",
- "rollup-plugin-node-resolve": "^3.0.2"
+ "rollup-plugin-commonjs": "^9.0.0",
+ "rollup-plugin-node-resolve": "^3.2.0"
},
"scripts": {
"prepublishOnly": "npm run build",
"build": "rollup -c",
- "test": "cross-env NODE_ENV=test jest",
- "travis": "jest && cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js",
+ "test": "jest",
+ "travis": "yarn run lint && jest && cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js",
"lint": "eslint ./src/**"
}
}
diff --git a/rollup.config.js b/rollup.config.js
index 34d3e4e..c044014 100644
--- a/rollup.config.js
+++ b/rollup.config.js
@@ -13,6 +13,7 @@ const globals = {
const config = {
input: 'src/index.js',
+ exports: 'named',
plugins: [
babel({
exclude: 'node_modules/**',
diff --git a/src/__snapshots__/index.test.js.snap b/src/__snapshots__/index.test.js.snap
deleted file mode 100644
index 130c4ea..0000000
--- a/src/__snapshots__/index.test.js.snap
+++ /dev/null
@@ -1,606 +0,0 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
-
-exports[`react-router-breadcrumbs-hoc Custom match options Should render empty container 1`] = `
-
-
-
-
-
-
- 1
-
-
- 1
-
-
-
-
-
-
-`;
-
-exports[`react-router-breadcrumbs-hoc No matching routes Should render empty container 1`] = `
-
-
-
-
-
-
-
-
-
-`;
-
-exports[`react-router-breadcrumbs-hoc Valid routes Should render breadcrumb components as expected 1`] = `
-
-
-
-
-
- Home
-
-
- 1
-
-
-
-
- TWO
-
-
-
-
-
-
- 3
-
-
-
-
-
-
-
-
- Link
-
-
-
-
-
-
-
-
-
-`;
-
-exports[`react-router-breadcrumbs-hoc When extending react-router config Should render expected breadcrumbs and omit routes that do not require them 1`] = `
-
-
-
-
-
-
-
-
-
-`;
diff --git a/src/index.js b/src/index.js
index 4ab3eb5..0b1406c 100644
--- a/src/index.js
+++ b/src/index.js
@@ -1,61 +1,117 @@
import { createElement } from 'react';
import { matchPath, withRouter } from 'react-router';
+import humanizeString from 'humanize-string';
const DEFAULT_MATCH_OPTIONS = { exact: true };
+const NO_BREADCRUMB = 'NO_BREADCRUMB';
-// if user is passing a function (component) as a breadcrumb, make sure we
-// pass the match object into it. Else just return the string.
-const renderer = ({ breadcrumb, match, location }) => {
+// renders and returns the breadcrumb complete with `match`, `location`, and `key` props
+const render = ({ breadcrumb, match, location }) => {
+ const componentProps = { match, location, key: match.path };
if (typeof breadcrumb === 'function') {
- return createElement(breadcrumb, { match, location });
+ return createElement(breadcrumb, componentProps);
}
- return breadcrumb;
+ return createElement('span', componentProps, breadcrumb);
};
-export const getBreadcrumbs = ({ routes, location }) => {
+// small helper method to get a default `humanize-string` breadcrumb if the
+// user hasn't provided one
+const getDefaultBreadcrumb = ({ pathSection, currentSection, location }) => {
+ const match = matchPath(pathSection, { ...DEFAULT_MATCH_OPTIONS, path: pathSection });
+
+ return render({
+ breadcrumb: humanizeString(currentSection),
+ match,
+ location,
+ });
+};
+
+// loops through the route array (if provided) and returns either
+// a user-provided breadcrumb OR a sensible default via `humanize-string`
+const getBreadcrumb = ({
+ currentSection,
+ excludePaths,
+ location,
+ pathSection,
+ routes,
+}) => {
+ let breadcrumb;
+
+ // check the optional `exludePaths` option in `options` to see if the
+ // current path should not include a breadcrumb
+ if (excludePaths && excludePaths.includes(pathSection)) {
+ return NO_BREADCRUMB;
+ }
+
+ // loop through the route array and see if the user has provided a custom breadcrumb
+ routes.some(({ breadcrumb: userProvidedBreadcrumb, matchOptions, path }) => {
+ if (!path) {
+ throw new Error('withBreadcrumbs: `path` must be provided in every route object');
+ }
+
+ const match = matchPath(pathSection, { ...(matchOptions || DEFAULT_MATCH_OPTIONS), path });
+
+ // if user passed breadcrumb: null OR custom match options to suppress a breadcrumb
+ // we need to know NOT to add it to the matches array
+ // see: `if (breadcrumb !== NO_BREADCRUMB)` below
+ if ((match && userProvidedBreadcrumb === null) || (!match && matchOptions)) {
+ breadcrumb = NO_BREADCRUMB;
+ return true;
+ }
+
+ if (match) {
+ breadcrumb = render({
+ // although we have a match, the user may be passing their react-router config object
+ // which we support. The route config object may not have a `breadcrumb` param specified.
+ // If this is the case, we should provide a default via `humanizeString`
+ breadcrumb: userProvidedBreadcrumb || humanizeString(currentSection),
+ match,
+ location,
+ });
+ return true;
+ }
+ return false;
+ });
+
+ // if there are no breadcrumbs provided in the routes array we return a default breadcrumb instead
+ return breadcrumb
+ || getDefaultBreadcrumb({
+ pathSection,
+ // include a "Home" breadcrumb by default (can be overrode or disabled in config)
+ currentSection: pathSection === '/' ? 'Home' : currentSection,
+ location,
+ });
+};
+
+export const getBreadcrumbs = ({ routes, location, options = {} }) => {
const matches = [];
const { pathname } = location;
pathname
- // remove trailing slash "/" from pathname (avoids multiple of the same match)
+ .split('?')[0]
+ // remove trailing slash "/" from pathname
.replace(/\/$/, '')
// split pathname into sections
.split('/')
// reduce over the sections and find matches from `routes` prop
- .reduce((previous, current) => {
- // combine the last route section with the current
+ .reduce((previousSection, currentSection) => {
+ // combine the last route section with the currentSection
// ex `pathname = /1/2/3 results in match checks for
// `/1`, `/1/2`, `/1/2/3`
- const pathSection = !current ? '/' : `${previous}/${current}`;
-
- let breadcrumbMatch;
-
- routes.some(({ breadcrumb, matchOptions, path }) => {
- if (!path) {
- throw new Error('withBreadcrumbs: `path` must be provided in every route object');
- }
- if (!breadcrumb) {
- return false;
- }
- const match = matchPath(pathSection, { ...(matchOptions || DEFAULT_MATCH_OPTIONS), path });
-
- // if a route match is found ^ break out of the loop with a rendered breadcumb
- // and match object to add to the `matches` array
- if (match) {
- breadcrumbMatch = {
- breadcrumb: renderer({ breadcrumb, match, location }),
- path,
- match,
- };
- return true;
- }
-
- return false;
+ const pathSection = !currentSection ? '/' : `${previousSection}/${currentSection}`;
+
+ const breadcrumb = getBreadcrumb({
+ currentSection,
+ excludePaths: options.excludePaths,
+ location,
+ pathSection,
+ routes,
});
- /* istanbul ignore else */
- if (breadcrumbMatch) {
- matches.push(breadcrumbMatch);
+ // add the breadcrumb to the matches array
+ // unless the user has explicitly passed { path: x, breadcrumb: null } to disable
+ if (breadcrumb !== NO_BREADCRUMB) {
+ matches.push(breadcrumb);
}
return pathSection === '/' ? '' : pathSection;
@@ -64,11 +120,14 @@ export const getBreadcrumbs = ({ routes, location }) => {
return matches;
};
-export const withBreadcrumbs = routes => Component => withRouter(props =>
+const withBreadcrumbs = (routes = [], options) => Component => withRouter(props =>
createElement(Component, {
...props,
breadcrumbs: getBreadcrumbs({
routes,
location: props.location,
+ options,
}),
}));
+
+export default withBreadcrumbs;
diff --git a/src/index.test.js b/src/index.test.js
index ab7ff55..e5106c1 100644
--- a/src/index.test.js
+++ b/src/index.test.js
@@ -3,20 +3,44 @@
import React from 'react';
import PropTypes from 'prop-types';
import { mount } from 'enzyme';
-import { StaticRouter as Router } from 'react-router';
+import { MemoryRouter as Router } from 'react-router';
import { NavLink } from 'react-router-dom';
-import { getBreadcrumbs, withBreadcrumbs } from './index';
+import withBreadcrumbs, { getBreadcrumbs } from './index';
const components = {
Breadcrumbs: ({ breadcrumbs }) => (
-
- {breadcrumbs.map(({ breadcrumb, path }, index) => (
- {breadcrumb}
+
+ {breadcrumbs.map((breadcrumb, index) => (
+
+ {breadcrumb}
+ {(index < breadcrumbs.length - 1) && / }
+
))}
-
+
),
BreadcrumbMatchTest: ({ match }) => {match.params.number} ,
BreadcrumbNavLinkTest: ({ match }) => Link ,
+ BreadcrumbLocationTest: ({ location: { state: { isLocationTest } } }) => (
+
+ {isLocationTest ? 'pass' : 'fail'}
+
+ ),
+};
+
+const render = ({
+ options,
+ pathname,
+ routes,
+ state,
+}) => {
+ const Breadcrumbs = withBreadcrumbs(routes, options)(components.Breadcrumbs);
+ const wrapper =
+ mount(TWO },
- // test advanced breadcrumb component (user can use `match` however they wish)
- { path: '/1/2/:number', breadcrumb: components.BreadcrumbMatchTest },
- // test NavLink wrapped breadcrumb
- { path: '/1/2/:number/4', breadcrumb: components.BreadcrumbNavLinkTest },
- // test a no-match route
- { path: '/no-match', breadcrumb: 'no match' },
- ];
- const routerProps = {
- context: {},
- location: { pathname: '/1/2/3/4' },
- };
-
it('Should render breadcrumb components as expected', () => {
- const ComposedComponent = withBreadcrumbs(routes)(components.Breadcrumbs);
- const wrapper = mount(TWO },
+ // test advanced breadcrumb component (user can use `match` however they wish)
+ { path: '/1/2/:number', breadcrumb: components.BreadcrumbMatchTest },
+ // test NavLink wrapped breadcrumb
+ { path: '/1/2/:number/4', breadcrumb: components.BreadcrumbNavLinkTest },
+ // test a no-match route
+ { path: '/no-match', breadcrumb: 'no match' },
+ ];
+ const { Breadcrumbs, wrapper } = render({ pathname: '/1/2/3/4', routes });
+ expect(Breadcrumbs.text()).toBe('Home / One / TWO / 3 / Link');
expect(wrapper.find(NavLink).props().to).toBe('/1/2/3/4');
});
});
- describe('No matching routes', () => {
- const routes = [
- { path: '/1', breadcrumb: '1' },
- ];
- const routerProps = {
- context: {},
- location: { pathname: 'nope' },
- };
-
- it('Should render empty container', () => {
- const ComposedComponent = withBreadcrumbs(routes)(components.Breadcrumbs);
- const wrapper = mount(