Skip to content

NiklasMencke/nextjs-breadcrumbs

Repository files navigation

nextjs-breadcrumbs

A dynamic, highly customizable breadcrumbs component for Next.js

NPM JavaScript Style Guide

Installation

yarn add nextjs-breadcrumbs

Prerequisites

This component is highly customizable. You can provide your own CSS via classes or via inline styles. If you want to use the default styling however, you need to make sure to import the CSS file provided by this package. Inside your _app.js paste import 'nextjs-breadcrumbs/dist/index.css'; at the top. This is not needed, if you just want to use your custom styles.

Usage

The component needs to be used within Next.js and won't work in plain React. It will always display a dynamic Breadcrumb navigation, based on the current path of the Next router.

import React from 'react';
import Breadcrumbs from 'nextjs-breadcrumbs';

const Example = () => {
  return <Breadcrumbs useDefaultStyle rootLabel="Home" />;
};

Pass custom list of characters that should be replaced in each label

By default the breadcrumb labels are generated through the url path. In many cases you might want to transform certain special characters from the path. One example would be transforming all the '.' into ' '. You can pass an array here with your preferred transformation list and the component will take care of that for you.

import React from 'react';
import Breadcrumbs from 'nextjs-breadcrumbs';

// Before: title.to.be.transformed  After: title to be transformed
const Example = () => {
  return (
    <Breadcrumbs
      useDefaultStyle={true}
      replaceCharacterList={[{ from: '.', to: ' ' }]}
    />
  );
};

Custom label transformation

It's possible to pass a label transformation function to customize the labels.

import React from 'react';
import Breadcrumbs from 'nextjs-breadcrumbs';

const Example = () => {
  return (
    <Breadcrumbs
      useDefaultStyle
      transformLabel={(title) => title + ' Custom Label'}
    />
  );
};

Omit the root / home label

It's possible to omit the root level entirely. This makes sense if you have an URL like https://website.com/home. If you wouldn't omit the root label in this case, the Breadcrumbs would show something like /home/home.

import React from 'react';
import Breadcrumbs from 'nextjs-breadcrumbs';

const Example = () => {
  return <Breadcrumbs omitRootLabel />;
};

Omit certain path indexes from breadcrumb navigation

It's possible to pass an array containing all the indexes of the path that should be omitted and not be rendered as labels. If we have a path like /home/category/1 then you might want to pass [2] here, which omits the breadcrumb label 1. Indexes start with 0. Example: [2] Default: undefined.

import React from 'react';
import Breadcrumbs from 'nextjs-breadcrumbs';

// path: /nested/this-is-ommited will omit the this-is-ommited breadcrumb
const Example = () => {
  return <Breadcrumbs useDefaultStyle={true} omitIndexList={[1]} />;
};

Custom styling (CSS)

It's possible, to style each HTML element of this component separetely. This can be done either via inline styles or by assigning your own classes.

Overview of props

Prop name Description Data type Example Default
useDefaultStyle If true, the default styles are used. Make sure to import the CSS in _app.js. boolean true false
rootLabel The title for the very first breadcrumb pointing to the root directory. string '/' 'HOME'
omitRootLabel Boolean indicator whether the root label should be omitted. boolean true false
labelsToUppercase Boolean indicator if the labels should be displayed as uppercase. boolean true false
replaceCharacterList Array containing a list of specific characters that should be replaced in the label. This can be useful to convert special characters such as vowels. Array [{ from: 'ae', to: 'ä' }, { from: '-', to: ' '}] [{ from: '-', to: ' ' }]
transformLabel A transformation function that allows to customize the label strings. Receives the label string and has to return a string or React Component. React.ReactNode (title) => 'Transformed ' + title null
omitIndexList Array containing all the indexes of the path that should be omitted and not be rendered as labels. If we have a path like '/home/category/1' then you might want to pass '[2]' here, which omits the breadcrumb label '1'. Indexes start with 0. Array [1] null
containerStyle An inline style object for the outer container Object null
containerClassName Classes to be used for the outer container. Won't be used if useDefaultStyle is true string null
listStyle An inline style object for the breadcrumb list Object null
listClassName Classes to be used for the breadcrumb list string null
inactiveItemStyle An inline style object for the inactive breadcrumb list item Object null
inactiveItemClassName Classes to be used for the inactive breadcrumb list item string null
activeItemStyle An inline style object for the active breadcrumb list item Object null
activeItemClassName Classes to be used for the active breadcrumb list item string null

License

MIT © NiklasMencke

Interfaces

nextjs-breadcrumbs / Exports / Breadcrumb

Interface: Breadcrumb

Table of contents

Properties

Properties

breadcrumb

breadcrumb: string

Breadcrumb title. Example: 'blog-entries'

Defined in: index.tsx:35


href

href: string

The URL which the breadcrumb points to. Example: 'blog/blog-entries'

Defined in: index.tsx:38

nextjs-breadcrumbs / Exports / BreadcrumbsProps

Interface: BreadcrumbsProps

Table of contents

Properties

Properties

activeItemClassName

Optional activeItemClassName: string

Classes to be used for the active breadcrumb list item

Defined in: index.tsx:78


activeItemStyle

Optional activeItemStyle: any

An inline style object for the active breadcrumb list item

Defined in: index.tsx:75


containerClassName

Optional containerClassName: string

Classes to be used for the outer container. Won't be used if useDefaultStyle is true

Defined in: index.tsx:60


containerStyle

Optional containerStyle: any

An inline style object for the outer container

Defined in: index.tsx:57


inactiveItemClassName

Optional inactiveItemClassName: string

Classes to be used for the inactive breadcrumb list item

Defined in: index.tsx:72


inactiveItemStyle

Optional inactiveItemStyle: any

An inline style object for the inactive breadcrumb list item

Defined in: index.tsx:69


labelsToUppercase

Optional labelsToUppercase: boolean

Boolean indicator if the labels should be displayed as uppercase. Example: true Default: false

Defined in: index.tsx:51


listClassName

Optional listClassName: string

Classes to be used for the breadcrumb list

Defined in: index.tsx:66


listStyle

Optional listStyle: any

An inline style object for the breadcrumb list

Defined in: index.tsx:63


rootLabel

Optional rootLabel: null | string

The title for the very first breadcrumb pointing to the root directory. Example: '/' Default: 'HOME'

Defined in: index.tsx:48


omitRootLabel

Optional omitRootLabel: boolean

Boolean indicator whether the root label should be ommitted. Example: true Default: false

Defined in: index.tsx:48


transformLabel

Optional transformLabel: (title: string) => string

A transformation function that allows to customize the label strings. Receives the label string and has to return a string

Type declaration

▸ (title: string): string

Parameters
Name Type
title string

Returns: string

Defined in: index.tsx:54


useDefaultStyle

Optional useDefaultStyle: boolean

If true, the default styles are used. Make sure to import the CSS in _app.js Example: true Default: false

Defined in: index.tsx:45

nextjs-breadcrumbs / Exports

nextjs-breadcrumbs

Table of contents

Namespaces

Interfaces

Variables

Variables

default

Const default: (__namedParameters: BreadcrumbsProps) => null | Element

A functional React component for Next.js that renders a dynamic Breadcrumb navigation based on the current path within the Next.js router navigation.

Only works in conjunction with Next.js, since it leverages the Next.js router.

By setting useDefaultStyle to true, the default CSS will be used. The component is highly customizable by either custom classes or inline styles, which can be passed as props.

param object of type BreadcrumbsProps

returns The breadcrumb React component.

Type declaration

▸ (__namedParameters: BreadcrumbsProps): null | Element

A functional React component for Next.js that renders a dynamic Breadcrumb navigation based on the current path within the Next.js router navigation.

Only works in conjunction with Next.js, since it leverages the Next.js router.

By setting useDefaultStyle to true, the default CSS will be used. The component is highly customizable by either custom classes or inline styles, which can be passed as props.

Parameters

Name Type
__namedParameters BreadcrumbsProps

Returns: null | Element

The breadcrumb React component.

Name Type
defaultProps BreadcrumbsProps

Defined in: index.tsx:109

Modules

nextjs-breadcrumbs / Exports / default

Namespace: default

Table of contents

Variables

Variables

defaultProps

defaultProps: BreadcrumbsProps