How to Customize the PageHeader with Title and Extra Content in refine-shadcn

Use the title and extra props in the PageHeader component to inject custom React nodes into the left and right sections of the header, enabling full control over headings and action areas without touching internal layout logic.

The PageHeader component serves as the standard header implementation for CRUD interfaces in the ferdiunal/refine-shadcn theme. Located in packages/theme/src/components/pageHeader.tsx, this component provides a flexible flexbox layout that separates content into distinct zones, making it simple to customize the PageHeader with title and extra content in refine-shadcn applications.

Understanding the PageHeader Architecture

The component is implemented in packages/theme/src/components/pageHeader.tsx with TypeScript definitions in packages/theme/src/types/pageHeader.d.ts. It renders a responsive container that divides the header into two primary areas: a left-aligned content block for titles and navigation, and a right-aligned block for actions.

The internal layout structure uses Tailwind CSS flexbox utilities:

<div className="flex h-20 items-end lg:justify-between …">
  <div className="min-w-0 flex-1">
    {/* title, subtitle, breadcrumb */}
  </div>
  <div className="flex lg:ml-4 lg:mt-0">{extra}</div>
</div>

Because both title and extra accept ReactNode types, you can pass plain text, styled JSX elements, or complex interactive components.

Core Props Reference

• title: ReactNode — The main heading displayed in the left zone. Accepts strings, JSX elements, or custom React components.
• extra: ReactNode — Content rendered in the right zone, typically used for action buttons, filter controls, or utility menus.
• subTitle: ReactNode — Secondary descriptive text rendered beneath the primary title.
• breadcrumb: ReactNode — Custom breadcrumb navigation. Defaults to the theme's <Breadcrumbs /> component when omitted.
• isBack: boolean — When set to true, automatically renders a back-arrow icon button.
• onBack: (e?) => void — Custom callback function for back navigation, overriding the default browser history behavior.
• className: string — Additional CSS classes applied to the root container for Tailwind customization.

Implementing Custom Title and Extra Content

Rendering Styled Titles with Action Buttons

To create a custom header with a styled title and multiple action buttons, pass JSX elements directly to the title and extra props:

import { PageHeader } from "@/components";

export const MyCustomPage = () => {
  return (
    <>
      <PageHeader
        title={<span className="text-primary">My Fancy Dashboard</span>}
        extra={
          <div className="flex gap-2">
            <button className="btn-primary">Refresh</button>
            <button className="btn-secondary">Settings</button>
          </div>
        }
        isBack
      />
      {/* page content */}
    </>
  );
};

The isBack prop automatically injects a back arrow that navigates to the previous route using the default history handler, or you can override it with onBack.

Overriding Headers in List Pages

The ListPage component in packages/theme/src/curds/list.tsx forwards title and extra props directly to PageHeader. This allows you to customize the header while retaining the list functionality:

import { ListPage } from "@/curds/list";

export const ProductList = () => {
  return (
    <ListPage
      title="Products"
      extra={
        <div className="flex gap-3">
          <input type="text" placeholder="Search…" className="input" />
          <button className="btn-primary">Add Product</button>
        </div>
      }
    />
  );
};

This pattern applies similarly to ShowPage in packages/theme/src/curds/show/index.tsx and CreatePage in packages/theme/src/curds/create.tsx, where default buttons (Edit/Delete for Show, List for Create) can be replaced or extended via the extra prop.

Configuring Subtitles and Custom Breadcrumbs

For detailed headers that require contextual information and navigation trails, combine the subTitle and breadcrumb props:

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

export const ProjectShow = () => {
  return (
    <PageHeader
      title="Project Apollo"
      subTitle="Mission-critical analytics platform"
      breadcrumb={
        <Breadcrumbs
          items={[
            { label: "Home", href: "/" },
            { label: "Projects", href: "/projects" },
          ]}
        />
      }
      extra={<button className="btn-outline">Export</button>}
    />
  );
};

Summary

• PageHeader is located in packages/theme/src/components/pageHeader.tsx and serves as the standard header for all CRUD pages in the ferdiunal/refine-shadcn theme.
• Use the title prop (accepts ReactNode) to customize the left-side heading content with text, styled elements, or complex JSX.
• Use the extra prop (accepts ReactNode) to populate the right-side action area with buttons, filters, or custom UI components.
• Enable automatic back navigation with isBack, or provide custom logic via onBack.
• The component is fully typed in packages/theme/src/types/pageHeader.d.ts and used by ListPage, ShowPage, and CreatePage components.

Frequently Asked Questions

What prop types does PageHeader accept for title and extra?

Both title and extra accept the ReactNode type, meaning you can pass strings, JSX elements, fragments, or entire component trees. This flexibility allows you to render anything from simple text to complex interactive widgets in the header zones.

How do I add a back button to the PageHeader?

Set the isBack prop to true to automatically render a back arrow icon that navigates using the default browser history. To customize the navigation behavior, provide a function to the onBack prop, which receives an optional event argument and overrides the default handler.

Can I use PageHeader outside of CRUD pages?

Yes. While PageHeader is imported and used by the standard CRUD implementations in packages/theme/src/curds/list.tsx, show/index.tsx, and create.tsx, you can import it directly from @/components and use it in any custom page layout throughout your application.

Where is the default breadcrumb logic defined?

When the breadcrumb prop is omitted, PageHeader renders the default <Breadcrumbs /> component. The breadcrumb items are typically generated automatically based on the current route, though you can override this by passing a custom ReactNode to the breadcrumb prop, as shown in the subtitle configuration example.

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