# Heading
> Heading component is used to create various levels of typographic hierarchies.

## Import

```js
import { Heading } from '@gemini-suite/vera-react';
```

## Examples

### Basic

Headings are intended to introduce sections of content. Use **Heading** to define a semantically relevant title to a component, content section or page.

<Callout variant="tip">

**Heading** should represent semantic value and give content some structure.
For general-purpose, body text, use [Text component](/components/typography/text).

</Callout>

```jsx
<Heading>I'm a Heading</Heading>
```

### Custom semantics

**Heading** component will render an `h1` element by default.
Other heading level elements `h1-h6` are available through use of the `as` property.

<Callout variant="important">

It is important to include a valid heading element to render a **Heading** component in order to maintain a coherent document outline.
Follow [semantic HTML guidelines](https://www.w3.org/WAI/tutorials/page-structure/headings/) when deciding which element to use and don't skip around in the hierarchy as this may misguide the user.

</Callout>

Note that the visual variant of a **Heading** can be controlled separately to which semantic element is used.

```jsx
<Heading as="h2" variant="gamma">
  An h2 with gamma variant
</Heading>
```

### Heading levels

By default, the semantic heading level matches the visual heading level.

```jsx
<Flex flow="column" gap="none">
  <Heading marginY="none">Heading one</Heading>
  <Heading as="h2" marginY="none">
    Heading two
  </Heading>
  <Heading as="h3" marginY="none">
    Heading three
  </Heading>
  <Heading as="h4" marginY="none">
    Heading four
  </Heading>
  <Heading as="h5" marginY="none">
    Heading five
  </Heading>
  <Heading as="h6" marginY="none">
    Heading six
  </Heading>
</Flex>
```

### Visual variants

Headings are split based on appearance into different variants.
These variants provide specific styles to the `font-size`, `font-weight`, and `line-height` of the text to create hierarchy that allow users to easily scan content.
Variants allow **Heading** semantics to be different from the visuals.

To change the visual variant, use the `variant` property.

```jsx
<Flex flow="column" gap="spacingL">
  <Flex flow="column" gap="none">
    <Heading as="h1" variant="giga" marginY="none">
      Heading one
    </Heading>
    <Heading as="h2" variant="alpha" marginY="none">
      Heading two
    </Heading>
    <Heading as="h3" variant="beta" marginY="none">
      Heading three
    </Heading>
    <Heading as="h4" variant="gamma" marginY="none">
      Heading four
    </Heading>
  </Flex>
  <Flex flow="column" gap="none">
    <Heading as="h3" variant="sectionTitle" marginY="none">
      Section title
    </Heading>
  </Flex>
</Flex>
```

### Responsive

You can make the **Heading** appearance differ across screen sizes, as `variant` property is responsive. It accepts both a single variant or an object that maps variants to [breakpoints defined in Vera](/tokens/breakpoints).

```jsx
<Heading
  variant={{
    '@initial': 'gamma',
    '@mqLargeAndUp': 'beta'
  }}
>
  Gamma variant on smaller screens
</Heading>
```

### Color

Default text color for **Heading** is inherited from the parent. When needed, you can override with a different text color using `color` property.

<Callout variant="tip">

Don't use accent colors or colors reserved for actions to make heading stand out more. Visual variants are sufficient to make it clear what is important.

</Callout>

```jsx
<Flex flow="column" gap="none">
  <Heading as="h3" marginY="none">
    Base
  </Heading>
  <Heading as="h3" marginY="none" color="foregroundNeutralModerate">
    Muted
  </Heading>
  <Heading as="h3" marginY="none" color="foregroundNeutralSubtle">
    Dim
  </Heading>
</Flex>
```

### Alignment

**Heading** text can be aligned via the `align` prop.

```jsx
<Flex flow="column" gap="spacingS">
  <Heading as="h3" marginY="none" align="left">
    Left
  </Heading>
  <Separator />
  <Heading as="h3" marginY="none" align="center">
    Center
  </Heading>
  <Separator />
  <Heading as="h3" marginY="none" align="right">
    Right
  </Heading>
  <Separator />
  <Heading
    as="h3"
    marginY="none"
    align={{
      '@initial': 'center',
      '@mqLargeAndUp': 'left'
    }}
  >
    Center on small screens
  </Heading>
</Flex>
```

### Overflow strategy

Use the `overflowStrategy` property to manage how **Heading** behaves with regard to overflow. For example, if you’re displaying user-generated content that may not fit within your layout, you can truncate text with the `overflowStrategy` set to `truncate`.

```jsx
<Flex flow="column" css={{ maxWidth: '36ch' }}>
  <Heading as="h4" marginY="none">
    <b>default:</b> Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
  </Heading>
  <Heading as="h4" marginY="none" overflowStrategy="truncate">
    <b>truncate:</b> Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
  </Heading>
  <Heading as="h4" marginY="none" overflowStrategy="nowrap">
    <b>nowrap:</b> Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
  </Heading>
  <Heading as="h4" marginY="none" overflowStrategy="breakword">
    <b>breakword:</b> Lorem ipsum dolor_sit_amet_consectetuer_adipiscing elit.
  </Heading>
</Flex>
```

### Tabular numbers

Enable `useTabularNumbers` property to make numeric glyphs have uniform/tabular widths (rather than proportional).
This enables columns of numbers to line up properly, which makes scanning numerical data easier and less error-prone.

```jsx
<Flex flow="column" gap="spacingXs">
  <Heading as="h3" marginY="none" useTabularNumbers>
    12121
  </Heading>
  <Heading as="h3" marginY="none" useTabularNumbers>
    90909
  </Heading>
</Flex>
```

---

## API Reference

<Callout variant="tip">

In addition to the props below, you can pass [Box props](/components/layout/box#api-reference) to control the spacing.

</Callout>

| Name                | Type                                                                                         | Default | Description                                                                                                                                                                                                                                                                                  | Required |
| ------------------- | -------------------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `as`                | `keyof JSX.IntrinsicElements \| React.ComponentType<any>`                                    | `h1`    | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.   For more details, read our [Composition](/get-started/composition#polymorphism) guide. |          |
| `css`               | `StitchesCss`                                                                                |         | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries or variants.                                                 |          |
| `variant`           | `"zeta" \| "epsilon" \| "delta" \| "gamma" \| "beta" \| "alpha" \| "giga" \| "sectionTitle"` |         | The visual variant of the heading. Available values are pulled from [typography tokens](/tokens/typography).                                                                                                                                                                                 |          |
| `color`             | `ColorToken`                                                                                 |         | The color of the heading. Subset of contrast-friendly foreground values from [color tokens](/tokens/colors) are available.                                                                                                                                                                   |          |
| `align`             | `"left" \| "center" \| "right"`                                                              |         | The horizontal alignment of the heading text.                                                                                                                                                                                                                                                |          |
| `useTabularNumbers` | `boolean`                                                                                    |         | When `true`, numbers in the heading will have the same width.                                                                                                                                                                                                                                |          |
| `overflowStrategy`  | `"wrap" \| "nowrap" \| "truncate" \| "breakword"`                                            |         | Controls how heading text behaves with regard to overflow.                                                                                                                                                                                                                                   |          |