Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nutgaard/react-router-breadcrumbs
Breadcrumb component for react-router
https://github.com/nutgaard/react-router-breadcrumbs
Last synced: 3 months ago
JSON representation
Breadcrumb component for react-router
- Host: GitHub
- URL: https://github.com/nutgaard/react-router-breadcrumbs
- Owner: nutgaard
- License: other
- Archived: true
- Created: 2016-02-21T13:07:33.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2020-06-01T01:15:12.000Z (over 4 years ago)
- Last Synced: 2024-09-24T22:33:51.419Z (3 months ago)
- Language: CSS
- Size: 5.53 MB
- Stars: 46
- Watchers: 3
- Forks: 11
- Open Issues: 21
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# react-router-breadcrumbs
A react-component for creating breadcrumbs based on your current active route.
[](https://circleci.com/gh/nutgaard/react-router-breadcrumbs/tree/master)
[](https://codecov.io/github/nutgaard/react-router-breadcrumbs?branch=master)
[](https://david-dm.org/nutgaard/react-router-breadcrumbs)
[](https://david-dm.org/nutgaard/react-router-breadcrumbs#info=devDependencies)
[](https://david-dm.org/nutgaard/react-router-breadcrumbs#info=peerDependencies)
[DEMO](http://www.utgaard.xyz/react-router-breadcrumbs)
## How to install
```
npm install react-router-breadcrumbs --save
```
## How to use it
The component is written with customization and ease-of-use in mind.
It therefore comes with some useful default which you can override if needed.
### The most basic setup
Using just the default provided by the component.
```jsx
```
### The default behaviour
The component takes five props in addition to `routes`.
| PropName | PropType | Default | Description |
| --------------------- | ----------------------------------------------------- | ------------- | ----------------------------------------------------- |
| `className` | `PropTypes.string` | `breadcrumbs` | The className for the `div` wrapping your breadcrumbs |
| `params` | `PropTypes.object` | `{}` | Typically the params from react-router |
| `resolver` | `PropTypes.func` | See below | A text resolver for customized texts |
| `createLink` | `PropTypes.func` | See below | Hook for overriding how links are created |
| `createSeparator` | `PT.oneOfType([PT.func, PT.string])` | See below | Hook for override how separators are created |
| `wrappingComponent` | `PT.string` | `div` | Determines the tagName for the wrapping component |
| `prefixElements` | `PT.oneOfType([PT.arrayOf(PT.element), PT.element])` | none | Elements to be added infront of the breadcrumb |
| `suffixElements` | `PT.oneOfType([PT.arrayOf(PT.element), PT.element])` | none | Elements to be added at the end of the breadcrumb |
```
// Default for `resolver` prop
const defaultResolver = (key, text, routePath, route) => key;
// Inputs and how they are determined:
// key: route.breadcrumbName || route.name || route.component.name
// text: paramsReplaced(key) (based on the `params` props)
// routePath: All current routes, except the last one
// route: Your current (last in -chain
```
```
// Default for `createLink` prop
const defaultLink = (link, key, text, index, routes) => {text};
// Inputs and how they are determined:
// link: The suggested href for this crumbs
// key: The suggested react-key
// text: The resulting text, either from the defaultResolver or your custom resolver
// routes: All current routes, including the last one
```
**NB! Its also possible to just send a `string` as this props-value.**
```
// Default for `createSeparator` prop
const defaultSeparator = (crumbElement, index, array) => > ;
// Inputs and how they are determined:
// crumb: The react-element (crumb) you are creating a separator after.
// index: The index of the current crumb
// array: All crumbs that a being generated
```
## Routes-customization
A lot-of customization can be done through the props of the component, but in many cases it will be enough to add props to your `Routes`.
The component looks for three specific props on the `Route` object.
1. `breadcrumbIgnore`, will remove the `Route` for any breadcrumb-path
2. `breadcrumbName`, will override the `Route.name` and sent to the `resolver`
3. `breadcrumbLink`, will override the `Route.path` and be subject to `params` replacement.
Which can be used to name your breadcrumbs exactly as you want.
### BreadcrumbIgnore Example
**NB. Theres is currently a bug where paths become wrong if this is used on a 'Route' with a path other then '/'**
```
// The example allways show 'Example' as its first breadcrumb.
// To remove this, add 'breadcrumbIgnore' as a prop
```
### BreadcrumbName Example
```
// To over the name-prop, we've added the breadcrumbName-prop.
// The resulting name will be sent to the resolver as the 'key' and i param-replaced form as 'text' (see resolver)
```
### BreadcrumbLink Example
```
// Overriding the path-prop
// NB. Can break functionality if abused
```
## Peer dependencies
This component has the newest react and react-router as peerdependenies, but will most likely work with lower version.
If you test the component with lower versions of react and/or react-router please let me know so that the dependencies can be adjusted.
```
"react": "^0.14.9 || ^15.3.0",
"react-dom": "^0.14.9 || ^15.3.0",
"react-router": "^2.0.1 || ^3.0.0"
```
In addition a polyfill for `Array.includes` is needed if you are targeting a browser which does not support this.
## Undocumented / TODO
1. If a breadcrumbLink and the route.path is both falsy the component uses a empty string. Suggest adding a default message/invariant/console.error to warn the user
## Example
The example can be seen at [http://www.utgaard.xyz/react-router-breadcrumbs](http://www.utgaard.xyz/react-router-breadcrumbs) and is greatly inspired by https://github.com/svenanders/react-breadcrumbs which provides a similar breadcrumb component.