Piral Breadcrumbs ·

This is plugin that only has a peer dependency to piral-core. What piral-breadcrumbs brings to the table is a set of Pilet API extensions that can be used with piral or piral-core.

Documentation

The following functions are brought to the Pilet API.

registerBreadcrumb()

Adds the definition of a breadcrumb to the app shell. Specifies display characteristics like the title, URL, or parent breadcrumb.

If the first argument is a string a named breadcrumb is registered. A named breadcrumb can also be removed.

unregisterBreadcrumb()

Removes a breadcrumb from the app shell. This requires a named breadcrumb.

Usage

::: summary: For pilet authors

You can use the registerBreadcrumb function from the Pilet API to add a new breadcrumb in the app shell.

Note: When the first argument is a string we call it a named breadcrumb.

Example use:

import { PiletApi } from '<name-of-piral-instance>';
 
export function setup(piral: PiletApi) {
  piral.registerBreadcrumb({
    title: 'Example',
    path: '/example',
  });
}

You can use the unregisterBreadcrumb function from the Pilet API to remove a previously added breadcrumb from the app shell.

Note: You'll need to have added a named breadcrumb in order to be able to remove it.

Example use:

import { PiletApi } from '<name-of-piral-instance>';
 
export function setup(piral: PiletApi) {
  // first register a named breadcrumb
  piral.registerBreadcrumb('bc-id', {
    title: 'Example',
    path: '/example',
  });
  // and unregister; maybe some time later?
  piral.unregisterBreadcrumb('bc-id');
}

:::

::: summary: For Piral instance developers

The provided library only brings API extensions for pilets to a Piral instance.

For the setup of the library itself you'll need to import createBreadcrumbsApi from the piral-breadcrumbs package.

import { createBreadcrumbsApi } from 'piral-breadcrumbs';

The integration looks like:

const instance = createInstance({
  // important part
  plugins: [createBreadcrumbsApi()],
  // ...
});

Via the options the initially available breadcrumbs can be defined.

Consider for example:

const instance = createInstance({
  // important part
  plugins: [createBreadcrumbsApi({
    breadcrumbs: [
      {
        path: '/example',
        title: 'Example',
      },
      {
        path: '/example/foo',
        title: 'Foo',
        parent: '/example',
      },
    ]
  })],
  // ...
});

Customizing

You can customize the breadcrumbs settings.

import type {} from 'piral-breadcrumbs';
 
declare module 'piral-breadcrumbs/lib/types' {
  interface PiralCustomBreadcrumbSettings {
    category?: string;
  }
}
 
// now registerBreadcrumb({ category: 'general' }) is strongly typed in pilets

:::

License

Piral is released using the MIT license. For more information see the license file.