@thojou/react-breadcrumb
A React component library for easy breadcrumb integration.
@thojou/react-breadcrumb is a simple breadcrumb component library for react apps.
It helps you implementing a visual breadcrumb component based on a nested structure. The main focus of this library is on managing state and providing the current breadcrumb data in a hierarchical order.
You can easily integrate this library with react-router-dom, react-redux, pick your favorite UI component library, or implement the UI components on your own.
Table of Contents
Install
In order to install @thojou/react-breadcrumb to your application, you need to run the following command from your project root
#npm
npm install --save @thojou/react-breadcrumb
#yarn
yarn add @thojou/react-breadcrumb
Usage
Wrap your page component body with the Breadcrumb
component
// components/Home.js
import React, { Component } from 'react';
import { Breadcrumb } from '@thojou/react-breadcrumb';
export class Home extends Component {
render () {
return (
<Breadcrumb
label="Home"
path="/"
>
<h1>Welcome to Homepage</h1>
</Breadcrumb>
);
}
};
Instead of using the
Breadcrumb
component, you can also wrap your existing component with an hoc.
// components/Home.js
import React, { Component } from 'react';
import { withBreadcrumb } from '@thojou/react-breadcrumb';
class Home extends Component {
render () {
return (
<h1>Welcome to Homepage</h1>
);
}
};
export const HomeWithBreadcrumb = withBreadcrumb('Home', '/')(Home);
Create your own presentational component to show the current breadcrumb path inside your UI.
// components/BreadcrumbPath.js
import React, { useContext } from 'react';
import { BreadcrumbStoreContext } from '@thojou/react-breadcrumb';
export function BreadcrumbPath() {
const {state} = useContext(BreadcrumbStoreContext);
render () {
return (
<ul>
{state.map((item) => (
<li key={item.path}>
<a href={item.path}>{item.label}</a>
</li>
))}
</ul>
);
}
};
Put it all together and wrap your application with the BreadcrumbStore
.
// app.js
import React, { Component } from 'react';
import { BreadcrumbStore } from '@thojou/react-breadcrumb';
import Home from './components/Home';
import BreadcrumbPath from './components/BreadcrumbPath';
class App extends Component {
render () {
return (
<BreadcrumbStore>
<BreadcrumbPath />
<Home />
</BreadcrumbStore>
);
}
};
Checkout the example project for a more complex use case.
react-redux
Usage withInternally @thojou/react-breadcrumb uses react reducers to manage the state. In large applications, you may be using react-redux for state management instead. You can easily integrate this project into react-redux with just some small adjustments.
This package ships with a built-in reducer and actions to update the represented state. You can reuse this implementation to move the state management into the redux store.
Note: If you are using react-redux for state management, wrapping your App inside
BreadcrumbStore
is not required.
Create a BreadcrumbContainer component to connect the breadcrumb to the redux store and use this container component instead of the origin Breadcrumb component.
import {connect} from 'react-redux';
import {Breadcrumb, addBreadcrumb, removeBreadcrumb } from '@thojou/react-breadcrumb';
export const BreadcrumbContainer = connect(
null,
{
addBreadcrumb,
removeBreadcrumb
}
);
Instead of using the BreadcrumbStoreContext
inside your presentational component, you should select the current state from you redux store.
// components/BreadcrumbPath.js
import React from 'react';
import {connect} from 'react-redux';
export function BreadcrumbPath({state}) {
render () {
return (
<ul>
{state.map((item) => (
<li key={item.path}>
<a href={item.path}>{item.label}</a>
</li>
))}
</ul>
);
}
};
export const BreadcrumbPathContainer = connect(
(state) => ({
state: state.breadcrumb
})
)(BreadcrumbPath);
API
Breadcrumb
Component props
import { Breadcrumb } from '@thojou/react-breadcrumb';
name | type | default | description |
---|---|---|---|
label | string | undefined | The label of this breadcrumb item |
path | string | "/" | The path of this breadcrumb item |
add | function | undefined | Custom function to add a breadcrumb to e.g. redux store |
remove | function | undefeined | Custom function to remove a breadcrumb from e.g. redux store |
withBreadcrumb
HOC props
import { withBreadcrumb } from '@thojou/react-breadcrumb';
name | type | default | description |
---|---|---|---|
label | string | undefined | The label of this breadcrumb item |
path | string | "/" | The path of this breadcrumb item |
You can pass addBreadcrumb
or removeBreadcrumb
to your enhanced component to override the default state management functions.
Example Project
Want to see this package in action? Have a look at codesandbox to see a working example or checkout this repository and start the example application by running the following commands:
cd example/
#npm
npm install
npm start
#yarn
yarn install
yarn start
Open a Browser and navigate to localhost:3000 to get started.
License
MIT © thojou