PageTitle

PageTitle

PageTitle is the shared page-header component for routed screens. It keeps the page's visible heading, breadcrumb trail, subtitle, inline header actions, and page-title context synchronized in one place.

Rationale

Use PageTitle when a page needs a single, consistent <h1> with optional breadcrumb navigation and shell-aware title synchronization. The component centralizes the page-header pattern so each route does not reimplement heading layout or page-title context updates.

Source References

• Source: frontend/src/components/core/PageTitle/index.tsx
• Tests: frontend/src/components/core/PageTitle/index.unit.test.tsx

Props

Name	Type	Required	Description
title	string	Yes	Visible page heading rendered as the <h1>.
subtitle	string	No	Optional supporting text rendered through Subtitle.
experimental	boolean	No	When true, renders the page-scoped UnderConstructionTag.
children	React.ReactNode	No	Optional inline content rendered beside the title, such as actions or status tags.
breadCrumbs	BreadCrumbType[]	No	Ordered breadcrumb entries used for visible navigation and for the shared page-title context value.

Supporting Type

type BreadCrumbType = {
  name: string;
  path: string;
};

Behavior

• Renders inside a Carbon Column with sm={4}, md={8}, and lg={16}.
• Uses TanStack Router's useNavigate() for breadcrumb navigation.
• Pushes a title into usePageTitle() whenever title or breadCrumbs change.
• Derives the shared page-title context from joined breadcrumb names when breadcrumbs exist; otherwise it falls back to title.
• Renders the title row in this order: <h1>, children, then UnderConstructionTag when experimental is true.

Examples

Happy path: standard page heading

import PageTitle from '@/components/core/PageTitle';

<PageTitle title="Dashboard" subtitle="Overview of your data" />;

Edge case: breadcrumbs, inline action, and experimental tag

import { Button } from '@carbon/react';

import PageTitle from '@/components/core/PageTitle';

<PageTitle
  title="Waste Search"
  subtitle="Browse and refine results"
  experimental
  breadCrumbs={[
    { name: 'Home', path: '/' },
    { name: 'Search', path: '/search' },
  ]}
>
  <Button kind="ghost" size="sm">
    Export
  </Button>
</PageTitle>;

Testing Notes

Current unit coverage verifies:

• title and subtitle rendering
• breadcrumb rendering and click handling
• experimental tag rendering
• child content rendering

The tests render PageTitle under both RouterProvider and PageTitleProvider, matching the component's runtime dependencies.

Known Constraints

• Breadcrumb path values must be valid TanStack Router to targets.
• PageTitle depends on PageTitleProvider; without it, usePageTitle() will fail.
• The shared page-title context uses breadcrumb names only. Subtitle text is not part of the derived title.

Change Impact

• codes/frontend/Components.md — catalog entry points to this page.
• development/conventions/Frontend Structure Guidelines.md — references PageTitle as the standard route-level <h1> provider.

See Also

• Subtitle
• Components