Overview

Heading controls page hierarchy, section titles, display titles, card titles, and documentation headings across all Byteion product screens. It is a Typography component that pairs a semantic level (which HTML tag to render) with a visual variant (how the text looks). Heading supports display sizes for landing pages, standard heading levels for document structure, body and muted variants for supporting text, plus code and kbd for technical inline elements.

Why this exists

Without a shared Heading component, every page uses ad-hoc heading sizes — text-2xl font-bold here, text-3xl font-semibold there — creating visual drift and inconsistent document outlines. Heading unifies page titles, section labels, card titles, and technical inline text into a single, accessible, token-based system. It ensures every page has a correct heading hierarchy that screen readers can navigate and search engines can parse.

Mental model

• Semantic level controls the document structure: h1 through h6. Screen readers and search engines rely on this to understand your page outline.
• Visual variant controls the appearance: display-2xl, display-xl, display-lg, h1–h4, body, muted, caption, code, kbd.
• Keep them separate. Do not pick h1 or h2 purely for visual size. Use the <Heading as="h2" variant="display-xl"> pattern when you need a display look with section-level semantics.
• One h1 per page. The page or primary screen title should be the only h1.

When to use

• Page titles — the primary heading that labels the current screen or view
• Dashboard section titles — major workspace areas like Orders, Analytics, Settings
• Settings page sections — Account, Notifications, Billing, Team as h2 headings
• Card titles — individual card or widget headings within a dashboard
• Modal and dialog titles — the heading inside a modal that describes its purpose
• Ecommerce admin / product edit screens — product name, SKU header, variant section titles
• ERP / POS workspace headers — invoice title, order ID, customer workspace labels
• Documentation content hierarchy — section titles, subsections, and technical reference labels

When not to use

• Do not use Heading for ordinary paragraph text unless using body, body-lg, or muted variants intentionally for styled text
• Do not use headings only to make text bigger — choose the correct semantic level first, then apply a visual variant if a display look is needed
• Do not use display variants in dense data tables — display sizes are for hero areas and landing sections, not table rows
• Do not use caption, code, or kbd as structural headings — these are inline text styles, not heading levels

Basic example

A standard page heading hierarchy with a title, section heading, and a card-level subsection:

<h1 class="text-3xl font-semibold tracking-tight text-foreground">Orders</h1>
<p class="text-sm text-muted-foreground">Manage and track all customer orders.</p>

<h2 class="text-2xl font-semibold tracking-tight text-foreground">Active orders</h2>
<p class="text-sm text-muted-foreground">Orders that are being processed or shipped.</p>

<h3 class="text-xl font-semibold text-foreground">Order #1024</h3>
<p class="text-sm text-muted-foreground">View details, update status, or cancel this order.</p>

Semantic hierarchy

Every page should follow a logical heading order. The as prop lets you decouple the rendered HTML tag from the visual variant:

Display headings

Display variants are intended for hero sections, landing pages, and prominent dashboard headers. They render as <h1> by default but can be overridden with the as prop:

Variants

The full variant set, grouped by purpose:

Truncation

The truncate prop adds the Tailwind truncate utility, which prevents text from wrapping and adds an ellipsis overflow. Use truncate for long dashboard titles, table row titles, project names, customer names, and report titles where layout width is limited:

<h2 class="text-2xl font-semibold tracking-tight text-foreground truncate">
  Annual Financial Report 2026 — Q4 Executive Summary
</h2>

Anatomy

• Heading element — an h1 through h6 tag for semantic headings, p for body/muted, span for caption, code for inline code, kbd for keyboard shortcuts
• Visual variant — controls font size, weight, tracking, and color via the variant classes
• Optional as prop — overrides the rendered HTML tag when semantics differ from the default variant mapping
• Optional truncate — adds text overflow ellipsis for constrained layouts

Usage guidelines

• Start every screen with one h1 that describes the current page or view
• Use h2 and h3 to divide product workflows and card sections
• Keep visual style and semantic structure separate — use the as prop when you need a display look on a section heading
• Use muted or caption for supporting metadata, not primary titles
• Use truncate for titles in constrained layouts like table rows, sidebar items, and card headers
• Test the page outline in browser developer tools to verify heading level order

Do and Don't

Accessibility

Heading renders real semantic HTML heading elements when the variant maps to h1–h4 or the as prop overrides the tag. This preserves the document outline for screen readers and search engines:

• One h1 per page — the primary screen or page title should be the only h1
• Logical heading order — follow h1 → h2 → h3 → h4 without skipping levels
• Do not skip levels for visual size — use the as prop to keep semantic structure correct while applying a display variant
• Do not use display variants to fake document structure — display-xl renders <h1> by default; override with <Heading as="h2" variant="display-xl"> for a display-sized section title
• Body, muted, caption, code, and kbd should not replace real headings — these variants render as <p>, <span>, <code>, or <kbd>, not heading tags
• Keyboard behavior — Heading has no keyboard interaction by itself. Interactive children (links, buttons) manage their own focus

Customization

Typography is customized through Byteion tokens — font family, font size scale, font weight, line height, tracking, and color variables. Each variant's classes are defined in the core Typography component via CVA and reference the standard Tailwind token scale. Avoid hardcoded arbitrary sizes unless intentionally extending the token scale. To add a new heading variant, extend the component's variant map or use the className prop with standard Tailwind utilities.

HTML example

<!-- Page hierarchy -->
<h1 class="text-3xl font-semibold tracking-tight text-foreground">Orders</h1>
<h2 class="text-2xl font-semibold tracking-tight text-foreground">Active orders</h2>
<h3 class="text-xl font-semibold text-foreground">Order #1024</h3>

<!-- Dashboard page header with title and muted description -->
<div>
  <h1 class="text-3xl font-semibold tracking-tight text-foreground">Analytics</h1>
  <p class="text-sm text-muted-foreground">Your store performance for the last 30 days.</p>
</div>

<!-- Card or settings section title -->
<h3 class="text-xl font-semibold text-foreground">Notifications</h3>

<!-- Display heading for landing section -->
<h1 class="text-5xl font-bold tracking-tight text-foreground">Build faster with Byteion</h1>

<!-- Truncated title -->
<h2 class="text-2xl font-semibold tracking-tight text-foreground truncate max-w-[250px]">
  Annual Financial Report 2026 — Q4 Executive Summary
</h2>

<!-- Inline code and kbd -->
<p>Run <code class="rounded bg-muted px-1.5 py-0.5 font-mono text-[0.85em] text-foreground">npm install</code> then press <kbd class="rounded border border-border bg-background px-1.5 font-mono text-[10px] text-muted-foreground">Ctrl+S</kbd></p>

React example

React exports the component as Typography from @byteion/react. Use the variant prop for visual style and the as prop to override the rendered HTML tag:

import { Typography } from '@byteion/react';

function PageHeader() {
  return (
    <div>
      <Typography variant="h1">Orders</Typography>
      <Typography variant="muted">
        Manage and track all customer orders.
      </Typography>
    </div>
  );
}

function SettingsSection() {
  return (
    <div>
      <Typography variant="h2">Notifications</Typography>
      <Typography variant="body">
        Configure which email and push updates you receive.
      </Typography>
    </div>
  );
}

function DashboardCard() {
  return (
    <div className="rounded-xl border border-border bg-card p-4">
      <Typography variant="h3" truncate>
        Annual Financial Report 2026 — Q4 Executive Summary
      </Typography>
      <Typography variant="caption">Updated 2 hours ago</Typography>
    </div>
  );
}

function LandingHero() {
  return (
    <Typography variant="display-xl" as="h2">
      Build faster with Byteion
    </Typography>
  );
}

function InlineExamples() {
  return (
    <p>
      Run <Typography variant="code">npm install</Typography>
      then press <Typography variant="kbd">Ctrl+S</Typography>
    </p>
  );
}

Vue example

Vue exports the component as Typography from @byteion/vue. The same variant and truncate props apply:

<script setup lang="ts">
import { Typography } from '@byteion/vue';
</script>

<template>
  <div>
    <Typography variant="h1">Orders</Typography>
    <Typography variant="muted">
      Manage and track all customer orders.
    </Typography>
  </div>

  <div class="rounded-xl border border-border bg-card p-4">
    <Typography variant="h3" :truncate="true">
      Annual Financial Report 2026 — Q4 Executive Summary
    </Typography>
    <Typography variant="caption">Updated 2 hours ago</Typography>
  </div>

  <p>
    Run <Typography variant="code">npm install</Typography>
    then press <Typography variant="kbd">Ctrl+S</Typography>
  </p>
</template>

API Reference

The Typography component is exposed as Typography in both @byteion/react and @byteion/vue. It provides heading, body, and inline text variants with automatic semantic tag rendering:

When using <Typography variant="h2" as="h1">, the component renders an <h1> tag with h2 visual styling. This is useful when you need a section-level heading styled as a page-level heading or vice versa. HTML-only projects apply the variant classes directly with semantic heading tags.

Developer tips

• Start every screen with a clear h1 — every page or primary view should have exactly one h1 that describes the current context
• Use h2 / h3 to divide product workflows — dashboard areas, settings groups, and card sections should each have a clear heading
• Keep visual style and semantic structure separate — use the as prop when you need a display look on a section heading
• Test long translated titles with truncate — text that works in English may be longer in other languages; truncate prevents layout breakage
• Check dark mode contrast — display and heading variants use text-foreground which adapts to dark mode; verify against background colours

Common mistakes

• Using h1 repeatedly for size — multiple h1 elements break the document outline. Use h2 for subsequent page areas
• Skipping heading levels — going from h1 to h4 confuses screen reader navigation; use the as prop to adjust visual size without breaking semantics
• Using muted or caption as structural headings — these variants render as <p> or <span>, not heading tags
• Using display headings in dense admin tables — display sizes are for hero areas; use h3 or h4 inside dashboard widgets and table headers
• Hardcoding one-off text sizes instead of using variants — if you need text-4xl font-extrabold, consider whether a display variant or a new variant entry is more sustainable

Production usage tips

• Audit the page outline — use browser developer tools or axe DevTools to verify heading levels are in logical order with no gaps
• Test responsive wrapping — display headings may overflow on small screens; test at 375 px, 768 px, and 1024 px breakpoints
• Test translated or long titles — enable truncate on any title that might wrap awkwardly in another language
• Confirm dark mode contrast — verify all heading foreground colours meet WCAG AA against their background in both light and dark themes
• Keep React / Vue variants aligned with the core schema — both frameworks share the same variant set; any variant added to one should be reflected in both

Premium examples

Pro patterns available in Byteion Pro:

• Dashboard page header — an h1 title paired with breadcrumbs, action buttons, and a status indicator in a page header cluster
• Ecommerce product edit title — a product name heading with an inline status badge and SKU label
• Analytics report heading group — a report title with muted description, date range filter, and export button in a compact toolbar
• ERP workspace header with tabs — an h2 section title above a tab bar for switching between invoices, orders, and customers
• Landing-page hero heading with gradient accent — a display-2xl heading with a gradient text effect and supporting lead paragraph

Related components

• Text — paragraph body text and description content
• Badge — inline status labels that can accompany headings
• Breadcrumb — page-level navigation paired with page titles
• Card — surface container where heading variants appear as card titles
• Section — page section primitive that pairs with h2 and h3 headings

API Reference

Related components

Pair this component with adjacent Byteion primitives from the same workflow: form controls for data entry, feedback components for validation, and layout primitives for spacing.

Runtime events

Byteion keeps framework APIs idiomatic: HTML uses DOM custom events, React uses callback props, and Vue uses emitted events / v-model updates.

Remote / AJAX