Properties

ariaLabel

Type: string

Default: breadcrumbs

Controls the aria-label on the parent element (<nav>).

Usage:

---
import { Breadcrumbs } from "astro-breadcrumbs";
---

<Breadcrumbs ariaLabel="a structured list of pages" />

Rendered Component:

1. Home
2. configuration
3. properties

customBaseUrl

Type: string

In most cases it is not necessary to enter the base url, as this value is taken from the Astro Config.

If your project has special requirements that make it impossible to use base, you can use customBaseUrl to overwrite the base url used by Astro.

Usage:

---
import { Breadcrumbs } from "astro-breadcrumbs";
---

<Breadcrumbs customBaseUrl="my-base-url" />

Rendered Component:

1. Home
2. configuration
3. properties

customizeLinks

Type: Array<CustomizeElement>

interface CustomizeElement {
  index?: number | "last";
  [key: string]: any;
}

Default: []

In case your preconfigured breadcrumbs are not sufficient, you can customize each link element individually. Therefore you can define an array of objects with the index of the element you want to customize. The index is the position of the element in the breadcrumbs array. The first element has the index 0, the second 1, and so on. If you want to customize the last element, you can use index: "last".

If you didn’t set a index the index of the array will be used.

Except index and text each key-value pair will be added as an attribute to the specific element.

text is the link text of the element.

Note

Existing attributes can’t be overwritten.

Usage:

---
import { Breadcrumbs } from "astro-breadcrumbs";

const customLastPart = [
  { index: "last", text: "Last page!" },
  {
    "data-link": "home",
    "aria-label": "Go to the home page",
    text: "Page 1",
  },
  {
    "data-link": "about",
    "aria-label": "Go to the about page",
    text: "Page 2",
  },
];
---

<Breadcrumbs customizeLinks={customLastPart} />

Rendered Component:

1. Page 1
2. Page 2
3. Last page!

customizeListElements

Type: CustomizeListElements[]

interface CustomizeListElements {
  index?: number | "last";
  remove?: boolean;
  [key: string]: any;
}

Default: []

Like customizeLinks you can customize each list element individually. Therefore you can define an array of objects with the index of the element you want to customize. The index is the position of the element in the breadcrumbs array. The first element has the index 0, the second 1, and so on. If you want to customize the last element, you can use index: "last".

If you didn’t set a index the index of the array will be used.

Except index and remove each key-value pair will be added as an attribute to the specific element.

When you set remove: true the element will be removed from the list.

Note

Existing attributes can’t be overwritten.

Usage:

---
import { Breadcrumbs } from "astro-breadcrumbs";

const customListItems = [
  { index: "last", "data-attribute": "Last page!" },
  {
    "data-attribute": "home",
    "aria-label": "Go to the home page",
  },
  {
    "data-attribute": "about",
    "aria-label": "Go to the about page",
  },
];
---

<Breadcrumbs customizeListElements={customListItems} />

Rendered Component:

1. Home
2. configuration
3. properties

customizeList

Type: AddAttributes

export interface AddAttributes {
  [key: string]: any;
}

Default: {}

Adds attributes to the <ol> list element. Each key-value pair will be added as an attribute to the specific element.

Note

Existing attributes can’t be overwritten.

Usage:

---
import { Breadcrumbs } from "astro-breadcrumbs";

const customList = {
  "data-attribute": "about",
  id: crypto.randomUUID(),
};
---

<Breadcrumbs customizeList={customList} />

Rendered Component:

1. Home
2. configuration
3. properties

customizeNav

Type: AddAttributes

export interface AddAttributes {
  [key: string]: any;
}

Default: {}

Adds attributes to the <nav> list element. Each key-value pair will be added as an attribute to the specific element.

Note

Existing attributes can’t be overwritten.

Usage:

---
import { Breadcrumbs } from "astro-breadcrumbs";

const customNav = {
  "aria-labelledby": "breadcrumb",
  id: crypto.randomUUID(),
};
---

<Breadcrumbs customizeNav={customNav} />

Rendered Component:

1. Home
2. configuration
3. properties

crumbs

Type:

interface BreadcrumbItem {
  text: string;
  href: string;
  "aria-current"?: string;
}

Default: []

This property expects an array of objects that describe the breadcrumbs “manually”. There are two required key value pairs: text: '' and href: '', every additional pair will add an attribute to this specific element. For example: title: 'Part of the breadcrumb list', will add an title attribute.

Note

If set dynamic creation will be disabled, indexText and baseUrl will have no affect.

Usage:

---
import { Breadcrumbs } from "astro-breadcrumbs";

const customCrumbs = [
  {
    text: "Custom Crumb 1",
    href: "#",
  },
  {
    text: "Custom Crumb 2 - I'm having custom title attribute",
    href: "#",
    title: "Part of the breadcrumb list",
  },
  {
    text: "Custom Crumb 3 - I'm having custom data attribute",
    href: "#",
    "data-custom": "custom data attribute",
  },
];
---

<Breadcrumbs crumbs={customCrumbs} />

Rendered Component:

1. Custom Crumb 1
2. Custom Crumb 2 - I'm having custom title attribute
3. Custom Crumb 3 - I'm having custom data attribute

debug

Type: boolean

Default: false

If set to true, the breadcrumbs will be displayed in a debug mode. This will show you the current configuration of the breadcrumbs in the terminal via console.table().

Usage:

---
import { Breadcrumbs } from "astro-breadcrumbs";
---

<Breadcrumbs debug={true} />

ellipsisAriaLabel

Type: string

Default: Show hidden navigation

aria-label of the ellipsis button (.c-breadcrumbs__truncated-button).

Usage:

---
import { Breadcrumbs } from "astro-breadcrumbs";
---

<Breadcrumbs ellipsisAriaLabel="a structured list of pages" />

Rendered Component:

1. Home
2. configuration
3. properties

excludeCurrentPage

Type: boolean

Default: false

If set to true, the current page will not be displayed in the breadcrumbs.

Note

This will not affect the schema.org JSON-LD script tag generation.

Usage:

---
import { Breadcrumbs } from "astro-breadcrumbs";
---

<Breadcrumbs excludeCurrentPage={true} />

Rendered Component:

1. Home
2. configuration

id

Type: string

Default: crypto.randomUUID()

The id of the breadcrumbs element.

Usage:

---
import { Breadcrumbs } from "astro-breadcrumbs";
---

<Breadcrumbs id="my-breadcrumbs" />

Rendered Component:

1. Home
2. configuration
3. properties

indexText

Type: string

Default: Home

Label of the first nav element.

Usage:

---
import { Breadcrumbs } from "astro-breadcrumbs";
---

<Breadcrumbs indexText="Home" />

Rendered Component:

1. Home
2. configuration
3. properties

linkTextFormat

Type: "lower" | "capitalized" | "sentence"

Controls the text transformation of all link texts.

• lower: Transforms the link text to lower case.
  • astro-breadcrumbs => astro breadcrumbs
• capitalized: Transforms the link text to capitalized case.
  • astro-breadcrumbs => Astro Breadcrumbs
• sentence: Transforms the link text to sentence case.
  • astro-breadcrumbs => Astro breadcrumbs

Note

This does not effect indexText.

Usage:

---
import { Breadcrumbs } from "astro-breadcrumbs";
---

<Breadcrumbs linkTextFormat="capitalized" />

Rendered Component:

1. Home
2. Configuration
3. Properties

mainBemClass

Type: string

Default: c-breadcrumbs

CSS BEM root class.

Caution

If you use the optional SCSS file, make sure you set the same class name in you’re SCSS config file. $bem-root needs to be adjusted.

Danger

If you use the optional CSS file, all styles will be broken. Please add your own CSS or use the SCSS styles with customized $bem-root prop.

Usage:

---
import { Breadcrumbs } from "astro-breadcrumbs";
---

<Breadcrumbs mainBemClass="o-bread-crumb" />

Rendered Component:

1. Home
2. configuration
3. properties

schemaJsonScript

Type: boolean

Default: true

Enable or disable the schema.org JSON-LD script tag generation.

Usage:

---
import { Breadcrumbs } from "astro-breadcrumbs";
---

<Breadcrumbs />

Rendered Component:

1. Home
2. configuration
3. properties

Output:

<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "BreadcrumbList",
    "itemListElement": [
      {
        "@type": "ListItem",
        "position": 1,
        "item": {
          "@id": "/",
          "name": "Home"
        }
      },
      {
        "@type": "ListItem",
        "position": 2,
        "item": {
          "@id": "/en",
          "name": "en"
        }
      },
      {
        "@type": "ListItem",
        "position": 3,
        "item": {
          "@id": "/en/properties",
          "name": "properties"
        }
      }
    ]
  }
</script>

separatorAriaHidden

Type: boolean

Default: true

Define the aria-hidden attribute of the separator element.

Usage:

---
import { Breadcrumbs } from "astro-breadcrumbs";
---

<Breadcrumbs separatorAriaHidden={false}>
  <svg
    slot="separator"
    xmlns="http://www.w3.org/2000/svg"
    width="24"
    height="24"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    stroke-width="2"
    stroke-linecap="round"
    stroke-linejoin="round"
    ><polyline points="9 18 15 12 9 6"></polyline>
  </svg>
</Breadcrumbs>

Rendered Component:

1. Home
2. configuration
3. properties

Output:

truncated

Type: boolean

Default: false

With the setting true, the breadcrumbs that no longer fit in a line are truncated and an ellipsis button is displayed.

Only the first element and the last element are displayed, with the ellipsis button in between.

A click on the ellipsis button shows all truncated elements.

The calculation is carried out using ResizeObserver and is therefore responsive.

The width of all elements is calculated together and compared with the available width. If the elements are larger than the available width, they are truncated.

Usage:

---
import { Breadcrumbs } from "astro-breadcrumbs";
---

<Breadcrumbs truncated={true} />

Caution

If you use the SCSS style file, you need to opt-in $truncated: true within the SCSS Style Api. (This does not apply to the CSS variant.)

astro-breadcrumbs-config.scss

@use "astro-breadcrumbs/breadcrumbs.scss" with (
  $truncated: true
);

Rendered Component:

1. Home
2. …
3. configuration
4. properties

Tip

Resize your browser until the breadcrumbs are truncated.

Deprecated Properties

baseUrl

Note

See migration to v2

Deprecated: v2.0.0

Type: string

Default: undefined

By default Astro-Breadcrumbs creates all links with relative urls. If you have other requirements you can use this property to customize the start of the url.

Note

Make sure you pass the the URL without a trailing slash. Otherwise you get an console warning and the URLs will be fallback to relative.

Caution

If you use custom crumbs, baseUrl will be disabled.

Usage:

---
import { Breadcrumbs } from "astro-breadcrumbs";
---

<Breadcrumbs baseUrl="https://base.url/page" />

trailingSlash

Note

See migration to v2

Deprecated: v2.0.0

Type: boolean

Default: false

If set to true all links will have a trailing slash.

Usage:

---
import { Breadcrumbs } from "astro-breadcrumbs";
---

<Breadcrumbs trailingSlash={true} />