# Title

> Slug: `title` · Category: Display

## When to use
- Render a page-level or section-level heading block with optional supporting body copy.
- Establish a visual hierarchy between primary and secondary content blocks.
- Provide the responsive max-width treatment Arrow's `tdds-title` applies (75% at 768px, 50% at 1024px).

## When NOT to use
- Heading inside a list row, card, or tight UI chrome — use `SectionHeader`.
- A full-bleed page title that should always be 100% width — use a raw `<h1 className="tdds:text-title-1">` to bypass `tdds-title`'s max-width.
- Just inline text — use a typography utility class directly.

## Variants & decision tree
- Top-of-page or hero -> `hierarchy="primary"` (Arrow `text-title-1` headline + `text-body-1` body).
- Section subheading -> `hierarchy="secondary"` (`text-title-2` + `text-body-2`).
- Centered alignment -> `alignment="center"` (adds `tdds:ta-center`).
- Heading semantics: pick `heading="h1"` for page level, `h2`+ for sections. Style is independent of semantic level.

## States
- Inverse-aware (theme or `inverse` prop).
- Returns `null` if `headline` is falsy — guards against empty headings.

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| **`headline`** | `ReactNode` | — | Heading content. **Passed as a prop, NOT children.** |
| `optionalBody` | `ReactNode` | — | Body copy below the headline. |
| `hierarchy` | `'primary' \| 'secondary'` | `'primary'` | Visual scale. |
| `heading` | `'h1' \| 'h2' \| ... \| 'h6'` | `'h1'` | Semantic heading element. |
| `alignment` | `'leading' \| 'center'` | `'leading'` | Text alignment. |
| `inverse` | `boolean` | inherits | Dark-background styling. |
| `className` | `string` | — | Extra class names. |

## Usage examples
```tsx
import { Title } from 'arrow-react-bootstrap';

// Page hero
<Title
  heading="h1"
  hierarchy="primary"
  headline="Find your next plan"
  optionalBody="Compare plans built for your life."
/>

// Section title, centered
<Title
  heading="h2"
  hierarchy="secondary"
  alignment="center"
  headline="What's included"
/>

// Title without body
<Title heading="h2" headline="Account details" />
```

## Composition
- Pair with `Button` / `ButtonTray` below for a hero-CTA pattern.
- Use `SectionHeader` instead when you need trailing controls (link, action button) on the same row.
- Compose with `tdds:container-md`, `tdds:pt-*` utilities for spacing.

## Accessibility
- Renders a real heading element (`h1`–`h6`) per `heading` prop — keep document outline correct.
- Use only one `h1` per page.
- Body is rendered as `<p>`, not a heading.

## Do / Don't
- Do: pass content via `headline`, never as children.
- Do: keep semantic `heading` matched to document hierarchy, even when visual `hierarchy` differs.
- Don't: nest interactive elements inside `headline`; this is presentational.
- Don't: rely on `Title` for full-bleed widths — use raw heading utilities when you need 100% width.
