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

> Learn to configure refine-shadcn breadcrumbs for intuitive navigation. Customize display options with props or global settings for an improved user experience. Essential for refine-shadcn developers.

- Repository: [Ferdi ÜNAL/refine-shadcn](https://github.com/ferdiunal/refine-shadcn)
- Tags: how-to-guide
- Published: 2026-03-01

---

**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`](https://github.com/ferdiunal/refine-shadcn/blob/main/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`](https://github.com/ferdiunal/refine-shadcn/blob/main/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`](https://github.com/ferdiunal/refine-shadcn/blob/main/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`](https://github.com/ferdiunal/refine-shadcn/blob/main/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.

```tsx
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.

```tsx
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.

```tsx
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`](https://github.com/ferdiunal/refine-shadcn/blob/main/packages/theme/src/ui/breadcrumb.tsx) for complete control over rendering.

```tsx
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`](https://github.com/ferdiunal/refine-shadcn/blob/main/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`](https://github.com/ferdiunal/refine-shadcn/blob/main/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`](https://github.com/ferdiunal/refine-shadcn/blob/main/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`](https://github.com/ferdiunal/refine-shadcn/blob/main/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.