@oerlikon/breadcrumbs

Provides simple react components to control the breadcrumb functionality of the app frame.

Disclaimer: This module depends on react-router-dom or @oerlikon/routing. If you indent to use a different routing system in your app, this module is not for you.

TOC

• setup
• usage
• gotcha

setup

Ensure the <BreadcrumbProvider> is placed high in your rendering tree, but insinde a routing provider (<BrowserRouter> from react-router-dom or <Router /> from @oerlikon/routing).

Props

sort: function to sort the breadcrumbs (see gotcha). By default the BreadcrumbProvider sorts by path prefix and length, this behaviour can be changes by providing a different sort function or be deactivated by setting this prop to false

Example with react-router-dom:

import { BrowserRouter } from 'react-router-dom';
import { render } from 'react-dom';
import { BreadcrumbProvider } from '@oerlikon/breadcrumbs';

import App from './App';

render(
  <BrowserRouter>
    <BreadcrumbProvider>
      <App />
    </BreadcrumbProvider>
  </BrowserRouter>,
  document.getElementById('root')
);

deepLink: boolean to activate / deactive the automated deep link integration. Defaults to true.

deepLinkPrefix: prefix for every generated deep link label. Defaults to an empty string.

usage

<Breadcrumb> component

Use the <Breadcrumb> component by providing a path and optionally deepLink as props and a label as children.

By setting deepLink to false, the deep link integration for this breadcrumb will be disabled. If you provide a string, that value will be used as the deep link label (defaults to children).

import React from 'react';
import { Breadcrumb } from '@oerlikon/breadcrumbs';

export const MyOverviewPage = () => {
  return (
    <>
      <Breadcrumb path="/overview">Overview</Breadcrumb>
      <h1>This is my overview</h1>
    </>
  );
};

useBreadcrumb() hook

Use the useBreadcrumb() hook by providing a path, a label and optionally a deepLink flag as parameters.

import React from 'react';
import { useBreadcrumb } from '@oerlikon/breadcrumbs';

export const MyOverviewPage = () => {
  useBreadcrumb({ path: '/overview', label: 'Overview', deepLink: false });
  return <h1>This is my overview</h1>;
};

gotcha

Because react components can re-render a lot during the lifetime of your app, the breadcrumbs can end up in an unpredictable order when they get pushed to or popped from the "global" breadcrumbs array. Thats why the BreadcrumbProvider uses a sort algorithm that expect your paths to be created hierarchically.

Lets assume you have a root page, a list page and a single view. The BreadcrumbProviders expect the following path hierarchy:

/root
/root/list
/root/list/singleId

Even when the list view re-renders and the list view paths gets pushed to the end of the breadcrumb array, the correct order is preserved.

This should work for the most projects as it is a common schema. If you have a different approach on creating paths, you can provide your own sort function to the Provider.