A typography primitive for semantic headings with library sizing and weight tokens.

API Reference

Heading is a moduix typography primitive. Base UI does not provide a matching heading primitive, so the public API stays focused on semantic element choice, visual variants, and root className composition.

Basic

Build reliable interfaces

import { Heading } from "moduix";export function HeadingDemo() {  return <Heading>Build reliable interfaces</Heading>;}

Full list of component variables available for project-level overrides.

Property	Default	Description
--heading-color	var(--color-foreground)	Controls heading text color.
--heading-font-family	var(--font-sans)	Controls heading font family.
--heading-font-size	size-dependent	Controls heading font size for all sizes.
--heading-font-size-xs	var(--text-sm)	Controls `xs` heading font size.
--heading-font-size-sm	var(--text-md)	Controls `sm` heading font size.
--heading-font-size-md	var(--text-lg)	Controls `md` heading font size.
--heading-font-size-lg	var(--text-xl)	Controls `lg` heading font size.
--heading-font-size-xl	var(--text-2xl)	Controls `xl` heading font size.
--heading-font-size-2xl	var(--text-3xl)	Controls `2xl` heading font size.
--heading-font-weight	var(--weight-semibold)	Controls heading font weight.
--heading-font-weight-bold	var(--weight-bold)	Controls `bold` heading font weight.
--heading-font-weight-medium	var(--weight-medium)	Controls `medium` heading font weight.
--heading-font-weight-regular	var(--weight-regular)	Controls `regular` heading font weight.
--heading-font-weight-semibold	var(--weight-semibold)	Controls `semibold` heading font weight.
--heading-letter-spacing	0	Controls heading letter spacing.
--heading-line-height	size-dependent	Controls heading line height for all sizes.
--heading-line-height-xs	var(--line-height-text-sm)	Controls `xs` heading line height.
--heading-line-height-sm	var(--line-height-text-md)	Controls `sm` heading line height.
--heading-line-height-md	var(--line-height-text-lg)	Controls `md` heading line height.
--heading-line-height-lg	var(--line-height-text-xl)	Controls `lg` heading line height.
--heading-line-height-xl	var(--line-height-text-2xl)	Controls `xl` heading line height.
--heading-line-height-2xl	var(--line-height-text-3xl)	Controls `2xl` heading line height.
--heading-text-wrap	balance	Controls heading text wrapping.

Interactive variables scoped for docs preview without changing size scale tokens.

Property	Default	Description
--heading-color	var(--color-foreground)	Controls heading text color.
--heading-font-family	var(--font-sans)	Controls heading font family.
--heading-letter-spacing	0	Controls heading letter spacing.
--heading-text-wrap	balance	Controls heading text wrapping.

Anatomy

Heading is composed as a single typography root that renders a semantic heading element. Visual style is controlled independently through size, weight, alignment, and CSS variables.

Heading
└─ text or inline content

Part	Role
`Heading`	Semantic heading root with design-system typography and tone props.

Composition

Use as for semantic heading level and size for visual scale when semantics and appearance should differ. Use weight, align, and className for presentation customization.

Heading has no hidden service slots; styling is done directly on the root element.

Examples

Elements

Use as to choose the semantic heading level. Each level has a matching default visual size.

Heading level 1

Heading level 2

Heading level 3

Heading level 4

Heading level 5

Heading level 6

import { Heading } from "moduix";export function HeadingElementsDemo() {  return (    <div className={styles.stack}>      <Heading as="h1">Heading level 1</Heading>      <Heading as="h2">Heading level 2</Heading>      <Heading as="h3">Heading level 3</Heading>      <Heading as="h4">Heading level 4</Heading>      <Heading as="h5">Heading level 5</Heading>      <Heading as="h6">Heading level 6</Heading>    </div>  );}

.stack {  display: flex;  width: min(32rem, calc(100vw - var(--spacing-8)));  flex-direction: column;  gap: var(--spacing-3);}

Sizes

Use size for visual sizing when the semantic level should stay separate from presentation.

Extra-large heading

Large heading

Medium-large heading

Medium heading

Small heading

Extra-small heading

import { Heading } from "moduix";export function HeadingSizesDemo() {  return (    <div className={styles.stack}>      <Heading as="h2" size="2xl">Extra-large heading</Heading>      <Heading as="h2" size="xl">Large heading</Heading>      <Heading as="h2" size="lg">Medium-large heading</Heading>      <Heading as="h2" size="md">Medium heading</Heading>      <Heading as="h2" size="sm">Small heading</Heading>      <Heading as="h2" size="xs">Extra-small heading</Heading>    </div>  );}

.stack {  display: flex;  width: min(32rem, calc(100vw - var(--spacing-8)));  flex-direction: column;  gap: var(--spacing-3);}

Weights

Use weight for the intended emphasis without adding a custom class.

Regular weight

Medium weight

Semibold weight

Bold weight

import { Heading } from "moduix";export function HeadingWeightsDemo() {  return (    <div className={styles.stack}>      <Heading as="h2" weight="regular">Regular weight</Heading>      <Heading as="h2" weight="medium">Medium weight</Heading>      <Heading as="h2" weight="semibold">Semibold weight</Heading>      <Heading as="h2" weight="bold">Bold weight</Heading>    </div>  );}

.stack {  display: flex;  width: min(32rem, calc(100vw - var(--spacing-8)));  flex-direction: column;  gap: var(--spacing-3);}

Alignment

Use align to set text alignment without adding custom CSS.

Left aligned

Center aligned

Right aligned

import { Heading } from "moduix";export function HeadingAlignedDemo() {  return (    <div className={styles.aligned}>      <Heading as="h2" align="left">Left aligned</Heading>      <Heading as="h2" align="center">Center aligned</Heading>      <Heading as="h2" align="right">Right aligned</Heading>    </div>  );}

.aligned {  display: flex;  width: min(32rem, calc(100vw - var(--spacing-8)));  flex-direction: column;  gap: var(--spacing-4);}

Semantic Level

Keep document outline and visual size independent by combining as and size.

Page title rendered as h2

import { Heading } from "moduix";export function SemanticHeadingDemo() {  return (    <Heading as="h2" size="2xl">      Page title rendered as h2    </Heading>  );}

Custom Styles

Pass className when styling the root with CSS Modules, Tailwind CSS, or CSS-in-JS.

Customized heading

import { Heading } from "moduix";export function CustomHeadingDemo() {  return (    <Heading as="h2" className={styles.customHeading}>      Customized heading    </Heading>  );}

.customHeading {  --heading-color: var(--color-primary);  --heading-font-size-xl: var(--text-3xl);  --heading-line-height-xl: var(--line-height-text-3xl);  --heading-font-weight-semibold: var(--weight-bold);}

Heading