How to Configure the Breadcrumbs Component for Navigation in refine-shadcn

Configure breadcrumbs in refine-shadcn by importing the Breadcrumbs wrapper from @/components and passing props like showHome or meta, or override globally via the options.breadcrumb field in the Refine provider.

The refine-shadcn UI kit provides a flexible breadcrumb navigation system built on top of shadcn/ui primitives and deeply integrated with Refine's routing logic. This guide explains how to configure the Breadcrumbs component for navigation in refine-shadcn using the wrapper component located in packages/theme/src/components/breadcrumbs.tsx and its underlying UI primitives.

Architecture of the Breadcrumbs System

The breadcrumb implementation follows a layered architecture that separates data resolution from UI rendering.

UI Primitives Layer

The low-level components reside in packages/theme/src/ui/breadcrumb.tsx. These primitives render the semantic <nav> structure using Tailwind CSS utilities and include Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, and BreadcrumbSeparator. They expose an asChild prop on BreadcrumbLink to support custom link components while maintaining default styling.

Breadcrumbs Wrapper Component

The Breadcrumbs component in packages/theme/src/components/breadcrumbs.tsx serves as the integration point with Refine's core. It calls the useBreadcrumb hook from @refinedev/core to resolve the current navigation trail from the resource tree and router location. The wrapper accepts two optional props: showHome (boolean) to toggle the dashboard link, and meta (any) which is forwarded to the hook for custom data provider logic.

Page-Level Integration

Standard CRUD templates (ListPage, ShowPage, EditPage, CreatePage) import Breadcrumbs and pass it to PageHeader via the breadcrumb prop. In packages/theme/src/curds/list.tsx, the implementation checks useRefineContext for global overrides while defaulting to the local Breadcrumbs component when no custom element is provided.

Global Configuration Override

You can replace the default breadcrumbs application-wide by setting options.breadcrumb in the <Refine> provider configuration. When provided, this React element renders instead of the default component unless a specific page explicitly overrides it via the breadcrumb prop on PageHeader.

Configuration Options and Props

Configure breadcrumb behavior through component props or global context settings.

Component Props

• showHome?: boolean: Controls whether to display a leading home/dashboard link. Defaults to true.
• meta?: any: Additional metadata passed to useBreadcrumb for custom breadcrumb resolution logic.

Global Context

• options.breadcrumb: Set in the <Refine> provider to substitute a custom breadcrumb component across all pages.

Page-Level Override

• breadcrumb prop on PageHeader: Accepts any React element to replace breadcrumbs for a specific view, bypassing both the default component and global settings.

Implementation Examples

Rendering Default Breadcrumbs

Import the component and let it auto-resolve the navigation trail from the current resource.

import { PageHeader, Breadcrumbs } from "@/components";

export const PostList = () => (
  <ListPage
    resource="posts"
    title="Posts"
    // Automatically renders <Breadcrumbs /> inside PageHeader
  />
);

Hiding the Home Link

Pass showHome={false} to remove the dashboard breadcrumb entry.

import { Breadcrumbs } from "@/components";

export const CategoryShow = () => (
  <ShowPage
    resource="categories"
    breadcrumb={<Breadcrumbs showHome={false} />}
  />
);

Setting a Global Custom Breadcrumb

Define a custom component at the application root to replace breadcrumbs everywhere.

import { Refine } from "@refinedev/core";
import { MyBreadcrumb } from "./components/MyBreadcrumb";

export default function App() {
  return (
    <Refine
      dataProvider={dataProvider}
      routerProvider={routerProvider}
      options={{ breadcrumb: <MyBreadcrumb /> }}
    />
  );
}

Building a Custom Breadcrumb Component

Use the UI primitives directly from packages/theme/src/ui/breadcrumb.tsx for complete control over rendering.

import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbSeparator, BreadcrumbPage } from "@/ui/breadcrumb";
import Link from "next/link";

export const MyBreadcrumb = () => (
  <Breadcrumb>
    <BreadcrumbList>
      <BreadcrumbItem>
        <BreadcrumbLink asChild>
          <Link href="/">Home</Link>
        </BreadcrumbLink>
      </BreadcrumbItem>
      <BreadcrumbSeparator />
      <BreadcrumbItem>
        <BreadcrumbPage>Custom Page</BreadcrumbPage>
      </BreadcrumbItem>
    </BreadcrumbList>
  </Breadcrumb>
);

Summary

• The Breadcrumbs component in packages/theme/src/components/breadcrumbs.tsx wraps useBreadcrumb from @refinedev/core to generate navigation trails automatically based on the current resource and route.
• Control the home link visibility with the showHome boolean prop, and pass custom metadata via the meta prop to influence breadcrumb generation logic.
• Override breadcrumbs globally using options.breadcrumb in the Refine provider, or per-page using the breadcrumb prop on PageHeader.
• For complete customization, import the base primitives from packages/theme/src/ui/breadcrumb.tsx and implement your own navigation logic using the asChild pattern for custom link components.

Frequently Asked Questions

How does the Breadcrumbs component resolve the navigation trail?

The component calls useBreadcrumb from @refinedev/core, which analyzes the current router location and the defined resource tree to generate an array of breadcrumb entries containing labels and optional hrefs. Each entry maps to BreadcrumbItem and BreadcrumbLink primitives in packages/theme/src/components/breadcrumbs.tsx, with the final item rendering as BreadcrumbPage to indicate the current location.

Can I use a custom link component instead of the default router link?

Yes. The UI primitives in packages/theme/src/ui/breadcrumb.tsx expose an asChild prop on BreadcrumbLink. When set to true, you can wrap your custom link component (such as Next.js Link or React Router Link) as a child element, and the primitive will clone it with the appropriate styling and attributes, ensuring full compatibility with your routing framework.

Why is the home breadcrumb showing even when I don't have a dashboard resource?

By default, showHome is set to true in the Breadcrumbs component. When enabled, the wrapper prepends a breadcrumb pointing to the first resource's list route and renders a HomeIcon when no custom icon is configured. Set showHome={false} on the component to disable this behavior, or configure the options.breadcrumb globally to a custom component that omits the home link entirely.

How do I add custom metadata to influence breadcrumb generation?

Pass an object to the meta prop on the Breadcrumbs component. This data is forwarded directly to useBreadcrumb, allowing your data provider or custom breadcrumb resolver to access additional context when generating the navigation trail labels or paths, such as including category names or dynamic route parameters.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}