import Example from "../../components/example";
import Exports from "../../components/exports";
import Layout from "../../components/layout";

import * as HeadingExports from "baseui/heading";

import Basic from "examples/heading/basic.tsx";
import DecoupleStyles from "examples/heading/decouple-styles.tsx";

import { Heading, HeadingLevel } from "baseui/heading";

export default Layout;

# Heading

**Headings are absolutely critical for screen reader users and it's important to correctly set their levels**. For example, you should never skip a level (having `h2` and not `h1` on the same page).

The problem is that levels are a question of context. When you move components with headings around, you need to check if levels still make sense and adjust them if not. That's a lot of mundane work and developers often rather take shortcuts such as using `h1` element only.

There is proposal for a native `<h>` element and [document outline algorithm](http://adrianroselli.com/2016/08/there-is-no-document-outline-algorithm.html) to solve this problem once for all but there is no browser support yet. In meantime, our `Heading` component uses [React Context](https://medium.com/@Heydon/managing-heading-levels-in-design-systems-18be9a746fa3) and implements its own document outline algorithm so developers don't have to think about it.

It is also possible to **decouple styles from the underlying `h1`-`h6` DOM elements**.

## Examples

<Example title="Heading basic usage" path="heading/basic.tsx">
  <Basic />
</Example>

Ideally, the user will use the default styles but sometimes it might make sense to set a fixed style no matter in what context the component was placed. You can decouple styles from levels through the `styleLevel` prop. However, **the proper `h1, h2 ... h6` hierarchy always stays in place**.

<Example
  title="Decouple and fix heading styles"
  path="heading/decouple-styles.tsx"
>
  <DecoupleStyles />
</Example>

<Exports
  component={HeadingExports}
  title="Heading exports"
  path="baseui/heading"
/>