N00b's Programming Machine

    react-router-breadcrumbs

    2.1.2 • Public • Published

    react-router-breadcrumbs

    A react-component for creating breadcrumbs based on your current active route.

    circleci.com codecov.io Dependency Status devDependency Status peerDependency Status

    DEMO

    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.

    <Breadcrumbs routes={routes} />

    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 <Route /> (last in <Route>-chain
    
    // Default for `createLink` prop
    const defaultLink = (link, key, text, index, routes) => <Link to={link} key={key}>{text}</Link>;
    
    // Inputs and how they are determined:
    // link:        The suggested href for this crumbs
    // key:         The suggested react-key <Component key={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) => <span key={`separator-${index}`}> &gt; </span>;
    
    // 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
    <Route path="/" name="Examples" component={App} breadcrumbIgnore > 
    

    BreadcrumbName Example

    // To over the name-prop, we've added the breadcrumbName-prop. 
    <Route name="UserDetails" path="details" component={UserDetails} breadcrumbName="Details" />
    
    
    // The resulting name will be sent to the resolver as the 'key' and i param-replaced form as 'text' (see resolver)
    <Route name="UserLocator" path=":userId" component={User} breadcrumbName=":userId">
    

    BreadcrumbLink Example

    // Overriding the path-prop
    // NB. Can break functionality if abused
    <Route path="/" name="Examples" component={App} breadcrumbLink="/my-application" >
    

    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 and is greatly inspired by https://github.com/svenanders/react-breadcrumbs which provides a similar breadcrumb component.

    Install

    npm i react-router-breadcrumbs

    DownloadsWeekly Downloads

    456

    Version

    2.1.2

    License

    X11

    Unpacked Size

    247 kB

    Total Files

    24

    Last publish

    Collaborators

    • nutgaard