Breadcrumbs

Breadcrumbs are a navigation tool that shows users where they are on a website and how to get back to previous pages.

import {QBreadcrumbs} from "@qui/react"

Overview

Breadcrumbs are configured using the QBreadcrumbItem interface.

Examples

Showcase

Breadcrumb items are compatible with any React flavor. The following example uses a Remix Link component via the item's render property.

import {ReactNode} from "react"

import {Link} from "react-router"

import {QBreadcrumbs} from "@qui/react"

export default function Showcase(): ReactNode {
  const items = [
    {
      label: "Home",
      render: <Link to="/" />,
    },
    {
      disabled: true,
      label: "Components",
      render: <Link to="/components" />,
    },
    {
      active: true,
      label: "Breadcrumbs",
      render: <Link to="/components/breadcrumbs" />,
    },
  ]

  return <QBreadcrumbs className="q-background-1" items={items} />
}

Icons

Use optional icon property to add an icon before text, and iconOnly property to show only icons, hover to see the text in tooltip.

import {ReactNode} from "react"

import {Files, FileText, Home} from "lucide-react"
import {Link} from "react-router"

import {QBreadcrumbItem, QBreadcrumbs} from "@qui/react"

export default function Icon(): ReactNode {
  const items: QBreadcrumbItem[] = [
    {icon: Home, label: "Home", render: <Link to="/" />},
    {
      disabled: true,
      icon: Files,
      label: "Components",
      render: <Link aria-label="Components" to="/components" />,
    },
    {
      active: true,
      icon: FileText,
      label: "Breadcrumbs",
      render: <Link aria-label="Breadcrumbs" to="/components/breadcrumbs" />,
    },
  ]

  const iconItems: QBreadcrumbItem[] = [
    {
      icon: Home,
      iconOnly: true,
      label: "Home",
      render: <Link aria-label="Home" to="/" />,
    },
    {
      disabled: true,
      icon: Files,
      iconOnly: true,
      label: "Components",
      render: <Link aria-label="Components" to="/components" />,
    },
    {
      active: true,
      icon: FileText,
      iconOnly: true,
      label: "Breadcrumbs",
      render: <Link aria-label="Breadcrumbs" to="/components/breadcrumbs" />,
    },
  ]

  return (
    <div>
      <div className="grid justify-center gap-4 py-4">
        <QBreadcrumbs className="q-background-1" items={items} />
      </div>
      <div className="grid justify-center gap-4 py-4">
        <QBreadcrumbs className="q-background-1" items={iconItems} />
      </div>
    </div>
  )
}

Breadcrumbs support two types of truncation: text and trail. With text truncation, each breadcrumb item's length is limited to a defined character amount. With trail truncation, a maximum of 5 breadcrumbs items are shown by default in the breadcrumb trail. If more than five items are supplied, the breadcrumb trails truncates to show the first and last items, and an ellipsis is rendered in between. Clicking the ellipsis shows the full breadcrumb bar.

import {ReactNode} from "react"

import {QBreadcrumbItem, QBreadcrumbs} from "@qui/react"

export default function Truncation(): ReactNode {
  const items: QBreadcrumbItem[] = [
    {label: "Primary"},
    {label: "Secondary"},
    {label: "Tertiary"},
    {label: "Quaternary"},
    {label: "Quinary"},
    {label: "Current Page"},
  ]

  return (
    <div>
      {/* Text truncation */}
      <div className="grid justify-center gap-4 py-4">
        <QBreadcrumbs className="q-background-1" items={items} truncation={8} />
      </div>
      {/* Trail truncation */}
      <div className="grid justify-center gap-4 py-4">
        <QBreadcrumbs
          className="q-background-1"
          items={items}
          truncation="trail"
        />
      </div>
    </div>
  )
}

Sizes

Use size property to set the size of the breadcrumb, options are s and m (default).

import {ReactNode} from "react"

import {Files, FileText, Home} from "lucide-react"
import {Link} from "react-router"

import {QBreadcrumbItem, QBreadcrumbs} from "@qui/react"

export default function Sizes(): ReactNode {
  const items: QBreadcrumbItem[] = [
    {icon: Home, label: "Primary", render: <Link to="/" />},
    {
      icon: Files,
      label: "Secondary",
      render: <Link to="/components/breadcrumbs" />,
    },
    {
      active: true,
      icon: FileText,
      label: "Current Page",
      render: <Link to="/components/breadcrumbs" />,
    },
  ]

  return (
    <div>
      {/* Small (s) */}
      <div className="grid justify-center gap-4 py-4">
        <QBreadcrumbs className="q-background-1" items={items} size="s" />
      </div>
      {/* Medium (m)*/}
      <div className="grid justify-center gap-4 py-4">
        <QBreadcrumbs className="q-background-1" items={items} />
      </div>
    </div>
  )
}

API

Items

The QBreadcrumbItem interface defines options like the label, icon, and link of a breadcrumb item.

Name & Description	Option(s)	Default
active If `true`, the item will render with an active style.	boolean
disabled When true, the breadcrumb item is disabled	boolean
icon lucide-react icon, positioned before the label	\| LucideIcon \| ReactNode
iconOnly shows only icon	boolean
id Identifier of the item	string
label Label text – the breadcrumb item's primary message	string
render Item renderer for overriding the default item	ReactElement	<div />
size Size of the breadcrumb item.	's' \| 'm'

active

Type

boolean

Description

If true, the item will render with an active style.

disabled

Type

boolean

Description

When true, the breadcrumb item is disabled

icon

Type

| LucideIcon
| ReactNode

Description

lucide-react icon, positioned before the label

iconOnly

Type

boolean

Description

shows only icon

Type

string

Description

Identifier of the item

label

Type

string

Description

Label text – the breadcrumb item's primary message

render

Type

ReactElement

Default

<div />

Description

Item renderer for overriding the default item

size

Type

's' | 'm'

Description

Size of the breadcrumb item.

Props

Name & Description	Option(s)	Default
items ^* Breadcrumb item array. The `QBreadcrumbItem` interface defines options like the label, icon, and link of a breadcrumb item.	QBreadcrumbItem[]
aria-label ARIA label for the breadcrumbs. See w3.org	string	'Breadcrumb'
as The component used for the root node. It can be a React component or element.	\| ElementType \| ComponentType	'ul'
className The className property of the Element interface gets and sets the value of the class attribute of the specified element.	string
listItemRender Customize the element used for the list item that wraps each breadcrumb item.	ElementType	'li'
size Applies a default size to each Breadcrumb item in this Breadcrumb. Note that each Breadcrumb item's size, if configured, will override this value.	's' \| 'm'	'm'
style The style global attribute contains CSS styling declarations to be applied to the element.	CSSProperties
truncation Truncates the breadcrumbs. When set to `'trail'`, a maximum of 5 items are shown by default in the breadcrumb trail. If more than 5 items are required, then the breadcrumb trail truncates to show the first and last items with an ellipsis shown to indicate further items. Supply as a number to customize the number of items shown.	\| 'trail' \| number

items

Type

QBreadcrumbItem[]

Description

Breadcrumb item array. The QBreadcrumbItem interface defines options like the label, icon, and link of a breadcrumb item.

aria-label

Type

string

Default

'Breadcrumb'

Description

ARIA label for the breadcrumbs. See w3.org

Type

| ElementType
| ComponentType

Default

'ul'

Description

The component used for the root node. It can be a React component or element.

className

Type

string

Description

The className property of the Element interface gets and sets the value of the class attribute of the specified element.

listItemRender

Type

ElementType

Default

'li'

Description

Customize the element used for the list item that wraps each breadcrumb item.

size

Type

's' | 'm'

Default

'm'

Description

Applies a default size to each Breadcrumb item in this Breadcrumb. Note that each Breadcrumb item's size, if configured, will override this value.

style

Type

CSSProperties

Description

The style global attribute contains CSS styling declarations to be applied to the element.

truncation

Type

| 'trail'
| number

Description

Truncates the breadcrumbs. When set to 'trail', a maximum of 5 items are shown by default in the breadcrumb trail. If more than 5 items are required, then the breadcrumb trail truncates to show the first and last items with an ellipsis shown to indicate further items. Supply as a number to customize the number of items shown.

Badge

Button