# Heading

Headings are used as the titles of each major section of a page in the
interface. Reserved for short and important text, Headings create a visual
hierarchy for the user.

## Design & usage guidelines

### Web

| Level                   | Use case                                                                                                                                                                                                                                |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<Heading level={1} />` | Should explain the main subject of the page. There should only be one `level={1}` Heading on a page                                                                                                                                     |
| `<Heading level={2} />` | Used to categorize large groups of content. For example, there are two main categories when creating a new client: client details and property details. This heading can be skipped if there are no large groups that need breaking up. |
| `<Heading level={3} />` | Used to group content and forms on a single topic.                                                                                                                                                                                      |
| `<Heading level={4} />` | Used to group contents after a `level={3}` Heading or inside a card component.                                                                                                                                                          |
| `<Heading level={5} />` | `level={5}` is used to group contents after a `level={4}` Heading.                                                                                                                                                                      |
| `<Heading level={6} />` | Used to group contents after a `level={5}` Heading or to group small lists of content.                                                                                                                                                  |

### Mobile

| Level                              | Use case                                                                                                                                                      |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<Heading level={"title"} />`      | Should explain the main subject of the page. There should only be one `title` Heading on a page.                                                              |
| `<Heading level={"subtitle"} />`   | Used to categorize large groups of content.                                                                                                                   |
| `<Heading level={"heading"} />`    | Used to group content and forms on a single topic. Like `title` and `subtitle`, `heading` uses [Jobber Pro](../Typography/Typography.md#component-view-font-families). |
| `<Heading level={"subHeading"} />` | Used to group small lists of content, `subHeading` uses the [Inter](../Typography/Typography.md#component-view-font-families) font.                                    |

## Content guidelines

The only content that should be used in a Heading is text. Use sentence-case for
headings. The exception is `Heading 6` in the web Headings, which is capitalized
as a stylistic reference to the
[eyebrow typographic pattern.](https://app.uxcel.com/lessons/basics-ii-588#eyebrow-headline-8095)

| ✅ Do                        | ❌ Don't                     |
| --------------------------- | --------------------------- |
| Job #21 for Nathaniel Lewis | Job #21 For Nathaniel Lewis |
| Save job and...             | Save Job And...             |
| Push notification settings  | Push Notification Settings  |

## Related components

For introductory text after a page title, or paragraph text for body copy, use
[Text](../Text/Text.md).

## Accessibility

In the web, HTML heading levels (h1, h2, h3, etc) correspond with document
structure for assistive technology. Designers should strive to use the right
level of heading visually to create an appropriate hierarchy, but in cases where
this is not desired you can still specify the correct semantic level of Heading
using the `element` property.

In mobile, assistive technology only picks up on whether or not a typographic
element is a heading or not, so the `element` property is not exposed.

## Platform considerations

There are a few caveats around copying text on Android and iOS that you can read
under the [Typography](../Typography/Typography.md) documentation.


## Component customization

### UNSAFE\_ props (advanced usage)

General information for using `UNSAFE_` props can be found
[here](../customizing-components/customizing-components.md).

**Note**: Use of `UNSAFE_` props is **at your own risk** and should be
considered a **last resort**. Future Icon updates may lead to unintended
breakages.

#### UNSAFE\_props (web)

### UNSAFE\_className

Use `UNSAFE_className` to apply custom classes to the Heading component. This can be
useful for applying styles via CSS Modules.

```tsx
<Heading level={1} UNSAFE_className={{ textStyle: styles.customHeading }}>
  Test with custom class name
</Heading>

// YourComponent.module.css
.customHeading {
  color: var(--color-red);
}
```

### UNSAFE\_style

Use `UNSAFE_style` to apply inline custom styles to the Heading component.

```tsx
<Heading level={1} UNSAFE_style={{ textStyle: { color: "red" } }}>
  Test with custom style
</Heading>
```

### Using the id prop

#### Do:

* ✅ Navigation anchors: Link directly to a specific section of the page (e.g.
  /docs#getting-started).
* ✅ Accessible regions: Provide an `id` so page regions (like `<section>`,
  `<fieldset>`, or form groups) can reference the heading via `aria-labelledby`,
  ensuring clear announcements without duplication.

#### Don't:

* ❌ CSS styling: Use design system props or `UNSAFE_className`/`UNSAFE_style`
  instead.


## Props

### Web

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `element` | `"h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "p" | "span"` | No | — | Allows overriding of the element rendered. Defaults to the heading specified with level. |
| `id` | `string` | No | — | Adds a unique identifier to the heading. Useful when the heading needs to be referenced by another element. Not inten... |
| `level` | `HeadingLevel` | No | `5` |  |
| `maxLines` | `"base" | "large" | "larger" | "single" | "small" | "unlimited"` | No | `unlimited` | The maximum amount of lines the text can occupy before being truncated with "...". Uses predefined string values that... |
| `UNSAFE_className` | `{ textStyle?: string; }` | No | — | **Use at your own risk:** Custom classNames for specific elements. This should only be used as a **last resort**. Usi... |
| `UNSAFE_style` | `{ textStyle?: CSSProperties; }` | No | — | **Use at your own risk:** Custom styles for specific elements. This should only be used as a **last resort**. Using t... |