Overview
SectionHeading provides consistent section headings with automatic spacing via CSS adjacent sibling selectors. No manual margin classes needed.
Key Features
- Three semantic levels (h2, h3, h4) with appropriate sizing
- Optional icon, description, badge, and divider props
- Subtle variant for form field group labels
- Icon size and color automatic based on level
Examples
Heading Levels
Three levels for page hierarchy: h2 for major sections, h3 for subsections, h4 for minor subsections.
Level 2: Major Section
Level 3: Subsection
Level 4: Minor Subsection
With Icon
Optional icon to the left of the heading. Size and color are automatic based on level.
Getting Started
Team Members
Advanced Options
AI Features
Subtle variant with icon uses muted color.
With Description
Notification Preferences
Control how and when we contact you
Team Settings
Set up your team and assign roles
Optional description text displayed below the heading in muted text.
With Badge
Optional badge for status indicators like Beta, New, or Pro.
Experimental Features
Advanced Settings
Recently Added
With Divider
Optional divider above, below, or both for visual separation.
Divider Above
Content after heading with top divider.
Divider Below
Content after heading with bottom divider.
Subtle Variant
Smaller uppercase label style for form field groups and card subsections.
Contact Information
Fields for name, email, and phone number would go here.
Address Details
Street, city, state, and zip code fields.
With Actions
Add buttons or other elements to the right side of the heading
Team Members
Manage your team members and their roles
Recent Activity
The actions prop accepts any ReactNode and displays it on the right side of the heading row, similar to PageHeader. Use for contextual actions like Add, View All, or Edit buttons.
Content Guidelines
How to write effective section headings at each level.
Level Semantics
level={2}Major SectionsContext: Page-level organization, primary navigation anchors
Style: Clear, action-oriented nouns or verb phrases
Examples: Overview, Settings, Team Members, Activity Feed
Always include an icon
level={3}SubsectionsContext: Content groups within major sections, card titles
Style: Descriptive nouns or noun phrases
Examples: Recent Activity, Heading Levels, Props Reference
Icon optional
level={4} subtleForm Field GroupsContext: Labeling groups of related form fields
Style: Short, uppercase label-style nouns
Examples: Contact Information, Address Details, Preferences
Always use subtle prop
Description Patterns
- Explain what the section contains or enables
- Keep to one sentence (5-15 words)
- Use present tense
Avoid
- Repeating information from the heading
- Multi-sentence descriptions or paragraphs
Good Examples
| Heading | Description |
|---|---|
| Team Members | Manage your team members and their roles |
| Privacy Settings | Control what information is visible to others |
| Recent Activity | No description needed |
Anti-Patterns
| ✗ Avoid | ✓ Instead |
|---|---|
| SectionHeading right after PageHeader with same text | Use PageHeader only, or different heading text |
| Multiple L2 headings in one PageCard | Use one L2 per PageCard, multiple L3s within it |
| L4 without subtle prop | Always use subtle prop with L4 |
Props Reference
| Prop | Type | Default | Description |
|---|---|---|---|
level | 2 | 3 | 4 | required | Semantic heading level: 2 (h2), 3 (h3), or 4 (h4) |
description | string | - | Optional subtitle text displayed below the heading |
badge | string | { label, variant } | - | Optional badge: string or object with label and variant |
divider | 'top' | 'bottom' | 'both' | - | Optional divider: 'top', 'bottom', or 'both' |
subtle | boolean | false | Smaller uppercase label-style variant |
icon | IconDefinition | - | Optional icon: size and color automatic based on level |
actions | ReactNode | - | Optional action elements (buttons, links) displayed on the right side |
className | string | - | Additional CSS classes for the container |
Usage
import { SectionHeading, Prose } from '@/ui/components';
import { Button } from '@/ui/primitives';
import { faBell, faGear } from '@fortawesome/duotone-regular-svg-icons';
// With icon (size/color automatic based on level)
<SectionHeading level={2} icon={faBell} description="Control notifications">
Notification Preferences
</SectionHeading>
// Icon colors by level:
// - Level 2: text-primary (branded)
// - Level 3: text-foreground (matches heading)
// - Level 4: text-foreground (matches heading)
// Parent container controls spacing
<div className="space-y-content">
<SectionHeading level={2} icon={faGear}>
Settings
</SectionHeading>
<Prose>Configure your account settings.</Prose>
</div>
// Subsection with badge
<SectionHeading level={3} badge="Beta">
Experimental Features
</SectionHeading>
// Subtle label style (form field groups)
<SectionHeading level={4} subtle>
Contact Information
</SectionHeading>
// With right-side actions (like PageHeader)
<SectionHeading
level={2}
description="Manage team members"
actions={<Button size="sm">Add Member</Button>}
>
Team
</SectionHeading>