# dds-heading



<!-- Auto Generated Below -->


## Overview

A page or section heading. `as` chooses the heading level, which is what gives the heading its place in the document outline; `size`, `weight` and `contrast` only style it, so a heading's level and its size are chosen separately.
Use for the titles of a page and its sections. Use `dds-text` for body text, captions and inline text.

## Usage

### Heading

#### Choosing the level

`as` sets the heading level, `h1` to `h6`, and it defaults to `h2`. Pick it for the document outline: one `h1` for the page, then `h2` for its sections, `h3` for their subsections, without skipping a level.

```html
<dds-heading as="h1">Campaign overview</dds-heading>
<dds-heading as="h2">Performance</dds-heading>
```

Any `as` outside `h1` to `h6` renders as an `h2`, so it is still a heading. For body text, captions and inline text use the text component.

Headings rendered by `dds-heading` live inside its shadow root. Assistive technology announces them as headings, but `document.querySelectorAll("h2")`, page CSS written against `h2` and an `aria-labelledby` pointing at them cannot reach them.

#### Size

`size` runs from `xl` (20px) to `10xl` (58px). When `size` is not set it follows `as`: `h1` is `4xl`, `h2` is `3xl`, `h3` is `2xl`, and `h4`, `h5` and `h6` are `xl`. Set `size` to change how the heading looks without changing its level, as in a section title that must stay an `h2` but should look like a page title.

```html
<dds-heading as="h2" size="5xl">A large section title</dds-heading>
```

The default sizes are provisional until the design team confirms them.

#### Display headings

Hero and campaign headings are the largest steps, `7xl` (42px) to `10xl` (58px). Set both the level and the size, since `as` alone gives a smaller heading.

```html
<dds-heading as="h1" size="9xl">Welcome to the campaign</dds-heading>
```

#### Weight and contrast

`weight` defaults to `bold`, which is the heaviest step. Use `normal`, `medium` or `semibold` for lighter headings. `contrast="low"` softens a heading that supports the content around it.

```html
<dds-heading as="h3" weight="semibold" contrast="low">Last 30 days</dds-heading>
```

#### Alignment and wrapping

`text-align` and `text-wrap` are inherited, so set them on the heading only to override what it would inherit. `text-wrap="balance"` evens out the lines of a short heading that wraps.

```html
<dds-heading as="h1" size="6xl" text-align="center" text-wrap="balance">
  A heading long enough to wrap onto two lines
</dds-heading>
```

#### Naming a heading

A heading's name is its text. To give it a different name for assistive technology, set `aria-label` on the `dds-heading`; it is passed to the heading inside.



## Properties

| Property    | Attribute    | Description                                                                                     | Type                                                                                                  | Default     |
| ----------- | ------------ | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------- |
| `as`        | `as`         | The heading level, which sets the heading's place in the document outline and its default size. | `"h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6"`                                                        | `"h2"`      |
| `contrast`  | `contrast`   | How strongly the heading stands out against its background.                                     | `"high" \| "low"`                                                                                     | `"high"`    |
| `size`      | `size`       | Which step of the type scale to render at. When not set, the size follows `as`.                 | `"10xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl" \| "7xl" \| "8xl" \| "9xl" \| "xl" \| undefined` | `undefined` |
| `textAlign` | `text-align` | Overrides the `text-align` the heading would inherit.                                           | `"center" \| "end" \| "justify" \| "start" \| undefined`                                              | `undefined` |
| `textWrap`  | `text-wrap`  | Overrides the `text-wrap` the heading would inherit.                                            | `"balance" \| "nowrap" \| "pretty" \| "wrap" \| undefined`                                            | `undefined` |
| `weight`    | `weight`     | How heavy the heading is.                                                                       | `"bold" \| "medium" \| "normal" \| "semibold"`                                                        | `"bold"`    |


## Slots

| Slot | Description       |
| ---- | ----------------- |
|      | The heading text. |


## Shadow Parts

| Part     | Description                         |
| -------- | ----------------------------------- |
| `"root"` | The heading element chosen by `as`. |


----------------------------------------------

*Built with [StencilJS](https://stenciljs.com/)*