# Heading

A semantic heading with an independent visual size.

```tsx
import { Heading } from "@/components/ui/heading"
import { Text } from "@/components/ui/text"
import { VStack } from "@/components/ui/stack"

export default function HeadingDemo() {
  return (
    <VStack gap={3}>
      <Heading>Project settings</Heading>
      <Text tone="muted">Manage your project and its members.</Text>
    </VStack>
  )
}
```

## Installation

**Command**

```bash
npx shadcn@latest add @arene/heading
```

Needs the [arene setup](https://www.arene.style/docs/installation) first. Also adds [Text](https://www.arene.style/docs/components/text).

**Manual**

1. Install the packages it imports:

   ```bash
   npm install @base-ui/react @stylexjs/stylex clsx
   ```

2. Set up the token layer. See [Installation](https://www.arene.style/docs/installation).
   Also copy [Text](https://www.arene.style/docs/components/text), which exports the shared typography maps.

3. Copy the component into your project.

   ```tsx title="components/ui/heading.tsx"
   "use client"

   import type { CSSProperties } from "react"
   import { useRender } from "@base-ui/react/use-render"
   import * as stylex from "@stylexjs/stylex"
   import type { StyleXStyles } from "@stylexjs/stylex"
   import { clsx } from "clsx"

   import { textStyles } from "@/components/ui/text"
   import { tracking } from "@/theme/tokens.stylex"

   const styles = stylex.create({ base: { letterSpacing: tracking.tight } })
   const sizes = {
     sm: textStyles.sizes.sm,
     base: textStyles.sizes.base,
     lg: textStyles.sizes.lg,
     xl2: textStyles.sizes.xl2,
     xl3: textStyles.sizes.xl3,
     xl4: textStyles.sizes.xl4,
   }
   const levelSizes = {
     1: "xl2",
     2: "lg",
     3: "base",
     4: "sm",
     5: "sm",
     6: "sm",
   } as const satisfies Record<number, keyof typeof sizes>
   const headingStyles = { base: styles.base, sizes, weights: textStyles.weights }

   type HeadingProps = useRender.ComponentProps<"h2"> & {
     level?: keyof typeof levelSizes
     size?: keyof typeof headingStyles.sizes
     weight?: keyof typeof headingStyles.weights
     xstyle?: StyleXStyles
     style?: CSSProperties
   }

   function Heading({
     render,
     ref,
     level = 2,
     size = levelSizes[level],
     weight = "semibold",
     xstyle,
     className,
     style,
     ...props
   }: HeadingProps) {
     const sx = stylex.props(
       styles.base,
       headingStyles.sizes[size],
       headingStyles.weights[weight],
       xstyle,
     )
     return useRender({
       defaultTagName: `h${level}`,
       render,
       ref,
       props: {
         "data-slot": "heading",
         "data-size": size,
         ...sx,
         ...props,
         className: clsx(sx.className, className),
         style: { ...sx.style, ...style },
       },
     })
   }

   export { Heading, headingStyles, type HeadingProps }
   ```

4. Change the `@/` imports if your project uses different aliases.

## Usage

```tsx
import { Heading } from "@/components/ui/heading"
```

```tsx
<Heading level={1}>Account settings</Heading>
```

`level` selects h1 through h6 and sets the default size. `size` overrides it
with `sm`, `base`, `lg`, `xl2`, `xl3` or `xl4` from [Text](https://www.arene.style/docs/components/text), and
does not change the heading level. `headingStyles` exports `base`, `sizes` and
`weights`.

## Level

Choose the level for the document outline. Each level has a default size: h1 is
`xl2`, h2 is `lg`, h3 is `base`, and h4 through h6 are `sm`.

```tsx
import { Heading } from "@/components/ui/heading"
import { VStack } from "@/components/ui/stack"

export default function HeadingLevel() {
  return (
    <VStack gap={3}>
      <Heading level={1}>Level 1</Heading>
      <Heading level={2}>Level 2</Heading>
      <Heading level={3}>Level 3</Heading>
      <Heading level={4}>Level 4</Heading>
      <Heading level={5}>Level 5</Heading>
      <Heading level={6}>Level 6</Heading>
    </VStack>
  )
}
```

## Size

Set `size` when a heading should look different from its level's default, such
as an h2 card title at `sm` or an h1 display heading at `xl4`.

```tsx
import { Heading } from "@/components/ui/heading"
import { VStack } from "@/components/ui/stack"

export default function HeadingSize() {
  return (
    <VStack gap={3}>
      <Heading size="sm">Contact details</Heading>
      <Heading size="base">Notifications</Heading>
      <Heading size="lg">Team members</Heading>
      <Heading size="xl2">Project settings</Heading>
      <Heading size="xl3">Account overview</Heading>
      <Heading size="xl4">Build with arene</Heading>
    </VStack>
  )
}
```

## Weight

Headings default to semibold and inherit the surrounding color.

```tsx
import { Heading } from "@/components/ui/heading"
import { VStack } from "@/components/ui/stack"

export default function HeadingWeight() {
  return (
    <VStack gap={3}>
      <Heading weight="normal">Normal heading</Heading>
      <Heading weight="medium">Medium heading</Heading>
      <Heading weight="semibold">Semibold heading</Heading>
      <Heading weight="bold">Bold heading</Heading>
    </VStack>
  )
}
```

## Composition

Pass `render` to choose a semantic element. Put its props on that element.

```tsx
import { Heading } from "@/components/ui/heading"

export default function HeadingRender() {
  return <Heading render={<h3 id="team">Team members</h3>} />
}
```

## API reference

See Base UI's [useRender reference](https://base-ui.com/react/utils/use-render)
for composition props. Native element props are forwarded.

| Prop        | Type                                 | Default        |
| ----------- | ------------------------------------ | -------------- |
| `level`     | `1 \| 2 \| 3 \| 4 \| 5 \| 6`         | `2`            |
| `size`      | `keyof typeof headingStyles.sizes`   | From `level`   |
| `weight`    | `keyof typeof headingStyles.weights` | `"semibold"`   |
| `render`    | `useRender.RenderProp`               | Native element |
| `xstyle`    | `StyleXStyles`                       | None           |
| `className` | `string`                             | None           |
| `style`     | `CSSProperties`                      | None           |

### Data attributes

| Attribute             | On   | Effect                   |
| --------------------- | ---- | ------------------------ |
| `data-slot="heading"` | root | Identifies the component |
| `data-size`           | root | The size in effect       |
