Skip to content
oks-ui

PageTitle component

PageTitle is a semantic heading component for page and section titles — it decouples the visual size from the actual heading level, so a title can look like an h1 while genuinely rendering as an h2 (or vice versa) to keep the document's real heading hierarchy correct regardless of visual design.

Layout & Display12 propsAccessibility notes

Playground

Change a prop on the right and the preview updates. Switch to Code to copy what you see.

Recipes

Copy-paste patterns for the ways PageTitle actually gets used — each one a real, self-contained example.

Title and subtitle

A page or section header — title plus an optional subtitle beneath it, at a consistent size across the app.

<PageTitle title="Billing" subtitle="Manage your plan and invoices" />

With a leading icon

icon renders before the title (iconPosition moves it to the end) — useful for a section that maps to a nav item.

<PageTitle
  icon={<SettingsIcon />}
  title="Settings"
  subtitle="Workspace preferences"
/>

Accent color

color tints the title — reach for it sparingly, to flag a section's status.

<PageTitle title="Danger zone" color="danger" />

Title and heading level

title is the heading content; as picks which semantic element actually renders (h1 through h6, defaulting to h4). Decide as based on the page's real document outline, not visual size — a section heading three levels deep in a page should be an h3/h4 even if it needs to look large.

<PageTitle as="h1" title="Dashboard" />
<PageTitle as="h3" title="Recent activity" />

Subtitle

subtitle renders secondary text below the title — a short description of what the page/section contains, or supplementary context that doesn't belong in the heading itself.

<PageTitle title="Team members" subtitle="Manage who has access to this workspace." />

Icon and color

icon renders next to the title, with iconPosition (start or end) controlling which side. color applies a semantic tint to the title text — leave it unset to inherit currentColor from the surrounding context, which is usually the right default for a heading meant to match its surrounding text color.

<PageTitle title="Billing" icon={<CreditCardIcon />} color="primary" />

Wrapping the title in a tooltip

For a title that benefits from extra context on hover (an abbreviation, a truncated long name), pass tooltip — true for a simple default, or an options object/content override for more control. It wraps just the title text, not the subtitle.

<PageTitle title="Q3 Revenue Forecast (FY26)" tooltip={{ content: "Fiscal year 2026, third quarter" }} />

Props

The full public API for PageTitle. Every prop is stable and intentionally typed.

Content

title

ReactNode

default: "Title"

Heading text/content.

icon

ReactNode

default: —

Icon rendered beside the title.

subtitle

ReactNode

default: —

Secondary text rendered below the title.

Appearance

color

"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger" | "black" | "white" | string

default: —

Text color; inherits currentColor when unset.

colorDepth

number

default: 500

Shade depth for the selected color.

iconPosition

"start" | "end"

default: start

Icon placement relative to the title.

Behavior & states

as

"h1" | "h2" | "h3" | "h4" | "h5" | "h6"

default: "h4"

Semantic heading element rendered.

tooltip

ReactNode | boolean | (Omit<TooltipProps, "children"|"content"> & { content?: ReactNode })

default: —

Wraps the title in a Tooltip. A plain value is shorthand content; bare true derives content from title; an object accepts any Tooltip prop plus an optional content override.

Events

onKeyDown

(e: KeyboardEvent<HTMLDivElement>) => void

default: —

Keydown handler on the root element.

Styling

className

string

default: —

Class applied to the root element.

classNames

Partial<Record<PageTitleSlot, string>>

default: —

Per-slot class overrides (base/title/icon/subtitle).

style

CSSProperties

default: —

Inline styles for the root element.

Accessibility

  • Renders as a genuine semantic heading element (h1-h6 via as) — never a styled <div> — so the page's heading outline stays correct for screen reader navigation (which commonly jumps between headings directly).
  • Choose as based on actual document structure, independent of how large the title needs to look — visual size and semantic level are two different decisions PageTitle deliberately keeps separate.
  • icon is decorative by default; if it conveys real information beyond what the title text already says, give it its own accessible label rather than relying on the title alone.

Best practices

  • Pick as by walking the page's real heading hierarchy (usually one h1 per page, then h2/h3 for sections) — don't default every PageTitle to the same level just because it's convenient.
  • Keep subtitle to one short sentence — it's supporting text under a heading, not a paragraph of body copy.
  • Use tooltip sparingly, only when the title text is genuinely truncated or abbreviated — wrapping every title in a tooltip "just in case" adds interaction noise without value.
  • Prefer letting color inherit (leave it unset) unless the title specifically needs to stand out with a semantic tint — most page titles should just match their surrounding text color.

More in Layout & Display