# Heading (/docs/heading)





## API Reference [#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 [#basic]

<Preview cssProperties="headingPlaygroundCssProperties">
  <HeadingExample />

  <Preview.Code>
    {`
          import { Heading } from "moduix";

          export function HeadingDemo() {
            return <Heading>Build reliable interfaces</Heading>;
          }
        `}
  </Preview.Code>

  <Preview.CSSProperties>
    {(context) => <HeadingCssPropertiesPanel {...context} />}
  </Preview.CSSProperties>

  <Preview.CSSPlayground>
    {(context) => <HeadingCssPlaygroundPanel {...context} />}
  </Preview.CSSPlayground>
</Preview>

## Anatomy [#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.

```text
Heading
└─ text or inline content
```

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

## Composition [#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 [#examples]

### Elements [#elements]

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

<Preview>
  <HeadingElementsExample />

  <Preview.Code>
    {`
          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>
            );
          }
        `}
  </Preview.Code>

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

### Sizes [#sizes]

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

<Preview>
  <HeadingSizesExample />

  <Preview.Code>
    {`
          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>
            );
          }
        `}
  </Preview.Code>

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

### Weights [#weights]

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

<Preview>
  <HeadingWeightsExample />

  <Preview.Code>
    {`
          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>
            );
          }
        `}
  </Preview.Code>

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

### Alignment [#alignment]

Use `align` to set text alignment without adding custom CSS.

<Preview>
  <HeadingAlignedExample />

  <Preview.Code>
    {`
          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>
            );
          }
        `}
  </Preview.Code>

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

### Semantic Level [#semantic-level]

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

<Preview>
  <HeadingSemanticExample />

  <Preview.Code>
    {`
          import { Heading } from "moduix";

          export function SemanticHeadingDemo() {
            return (
              <Heading as="h2" size="2xl">
                Page title rendered as h2
              </Heading>
            );
          }
        `}
  </Preview.Code>
</Preview>

### Custom Styles [#custom-styles]

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

<Preview>
  <CustomStylesHeadingExample />

  <Preview.Code>
    {`
          import { Heading } from "moduix";

          export function CustomHeadingDemo() {
            return (
              <Heading as="h2" className={styles.customHeading}>
                Customized heading
              </Heading>
            );
          }
        `}
  </Preview.Code>

  <Preview.CSS>
    {`
          .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);
          }
        `}
  </Preview.CSS>
</Preview>