> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Heading Component

## Article: Heading Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/typography/heading-component.md

## Article Content:

# Heading

_Components/Typography_

Interactive docs page: <https://wix-pages.com/design-system-documentation/#/component/heading>

## Overview

```jsx
<Box align="center">
  <Heading>Contact List</Heading>
</Box>;
```

Headings are titles for the main sections of a page. They help users understand what a page or section is about at a glance.

### Do

- Use headings to describe each section on a page.
- Keep the heading text short and clear.
- Keep the entire heading text visible at all times. Make sure it doesn't get truncated with an ellipsis.
- Follow a sequential, descending heading order, and don't skip levels.

### Don't

- Don't use headings for paragraphs of text or titles with multiple sentences. Use `<Text/>` instead.
- Don't use headings for content that isn't a heading.

### Feature examples

#### Size

Control the size of a heading with the `size` prop.

- `extraLarge` (heading tag – h1)
- `large` (h2)
- `medium` (h3)
- `small` (h4)
- `tiny` (h5)
- `extraTiny` (h6)

Note: Building a page with proper heading structure is essential for accessibility. If the heading size has a tag that doesn't fit the structure, it should be overridden using the `as` prop (see the 'Custom HTML tag' section).

```jsx
<StorybookComponents.Stack flexDirection="column">
  <Heading size="extraLarge">XL - Page Title (e.g., Contact List)</Heading>
  <Heading size="large">L - Modal title (e.g., Create a new contact)</Heading>
  <Heading size="medium">M - Card title (e.g., Subscribers)</Heading>
  <Heading size="small">S - Page section title (e.g., Contact info)</Heading>
  <Heading size="tiny">T - Card section title (e.g., Notes)</Heading>
  <Heading size="extraTiny">XT - Caption (e.g., Last activity)</Heading>
</StorybookComponents.Stack>;
```

#### Light

Invert the skin of a heading with the `light` prop. Use this skin for headings on backgrounds with colors or images.

```jsx
<StorybookComponents.Background skin="dark">
  <StorybookComponents.Stack flexDirection="column" padding="30px">
    <Heading size="extraLarge" light>
      XL - Page Title (e.g., Contact List)
    </Heading>
    <Heading size="large" light>
      L - Modal title (e.g., Create a new contact)
    </Heading>
    <Heading size="medium" light>
      M - Card title (e.g., Subscribers)
    </Heading>
    <Heading size="small" light>
      S - Page section title (e.g., Contact info)
    </Heading>
    <Heading size="tiny" light>
      T - Card section title (e.g., Notes)
    </Heading>
    <Heading size="extraTiny" light>
      XT - Caption (e.g., Last activity)
    </Heading>
  </StorybookComponents.Stack>
</StorybookComponents.Background>;
```

#### Ellipsis

By default, the header wraps if the text is too long, but can be truncated at the end of a sentence with the `ellipsis` prop.

Note: For accessibility, avoid using the `ellipsis` prop on headings. Keep all heading text visible on the screen at all times.

```jsx
<StorybookComponents.Stack width="400px">
  <Heading ellipsis>Create specific audiences with Segments</Heading>
</StorybookComponents.Stack>;
```

#### Children

Render any kind of component within the `<Heading> `tag. This is most commonly used to display an alternative style of text inline with the title.

```jsx
() => {
  const renderHeadingWithDifferentColor = () => (
    <Box marginLeft="SP1" color="D40" inline>
      5
    </Box>
  );
  return (
    <Heading>
      Contact List
      {renderHeadingWithDifferentColor()}
    </Heading>
  );
};
```

#### Custom HTML tag

Render the heading as an HTML tag with the `as` prop.

- Using `<h1>` to `<h6>` overrides the default size heading tag. This is useful for creating an accessible page heading structure without changing the design.
- `<div>` or `<span>` can be used when a heading shouldn't be perceived as a title.

All attributes will be passed to the rendered HTML tag.

```jsx
<Heading size="medium" as="h1">
  Medium size heading that appears as the main page header h1
</Heading>;
```

### Common use case examples

#### Content hierarchy

Use headings to emphasize main sections of a page and group related content together.

```jsx
() => {
  const [address, setAddress] = React.useState('');

  const renderProfile = () => {
    return (
      <Cell>
        <Layout>
          <Cell>
            <Page.Section title="Main info" showDivider />
          </Cell>
          <Cell span={12}>
            <Card>
              <Card.Header title={<Heading size="medium">Profile</Heading>} />
              <Card.Divider />
              <Card.Content>
                <Layout>
                  <Cell span={8}>
                    <FormField label="Business name">
                      <Input placeholder="" />
                    </FormField>
                  </Cell>
                  <Cell span={8}>
                    <FormField label="Description">
                      <InputArea
                        placeholder="Use short, catchy text to tell people what your business offers."
                        minHeight="120px"
                      />
                    </FormField>
                  </Cell>
                </Layout>
              </Card.Content>
            </Card>
          </Cell>
        </Layout>
      </Cell>
    );
  };
  const renderLocationAndAddress = () => (
    <>
      <Cell span={12}>
        <Heading size="tiny">Location</Heading>
        <Text size="small" secondary>
          Let customers know where your business is based. You can add one or
          multiple locations.
        </Text>
      </Cell>
      <Cell span={8}>
        <FormField label="Address">
          <AddressInput
            value={address}
            border="standard"
            onChange={(event) => setAddress(event.target.value)}
            onClear={() => setAddress('')}
          />
        </FormField>
      </Cell>
    </>
  );

  const renderContactInfo = () => (
    <>
      <Cell span={12}>
        <Heading size="tiny">Contact info</Heading>
        <Text size="small" secondary>
          Add your business details so people can get in touch easily.
        </Text>
      </Cell>
      <Cell span={4}>
        <FormField label="Email">
          <Input placeholder="" />
        </FormField>
      </Cell>
      <Cell span={4}>
        <FormField label="Phone">
          <Input placeholder="" />
        </FormField>
      </Cell>
    </>
  );

  const renderBusinessHours = () => (
    <>
      <Cell span={12}>
        <Heading size="tiny">Business hours</Heading>
        <Text size="small" secondary>
          Tell customers when your business is open.
        </Text>
      </Cell>
      <Cell span={8}>
        <Box
          padding="SP3 SP4"
          border="1px solid #c1e4fe"
          borderRadius="6px"
          verticalAlign="middle"
          align="space-between"
        >
          <Box direction="vertical" gap="3px">
            <Text size="small" weight="bold">
              Everyday
            </Text>
            <Text size="small" secondary>
              6:00AM - 8:00PM
            </Text>
          </Box>
          <Box>
            <TextButton size="small" prefixIcon={<Icons.EditSmall />}>
              Edit
            </TextButton>
          </Box>
        </Box>
      </Cell>
    </>
  );

  const renderLocationAndContactInfo = () => {
    return (
      <Cell>
        <Layout>
          <Cell>
            <Page.Section
              title="Location and contact info"
              showDivider
              actionsBar={
                <TextButton prefixIcon={<Icons.Add />}>Add Location</TextButton>
              }
            />
          </Cell>
          <Cell span={12}>
            <Card>
              <Card.Header
                title={<Heading size="medium">Default info</Heading>}
              />
              <Card.Divider />
              <Card.Content>
                <Layout>
                  {renderLocationAndAddress()}
                  <Cell span={12}>
                    <Divider />
                  </Cell>
                  {renderContactInfo()}
                  <Cell span={12}>
                    <Divider />
                  </Cell>
                  {renderBusinessHours()}{' '}
                </Layout>
              </Card.Content>
            </Card>
          </Cell>
        </Layout>
      </Cell>
    );
  };

  return (
    <Page>
      <Page.Header title="Business Info"></Page.Header>
      <Page.Content>
        <Layout>
          {renderProfile()}
          {renderLocationAndContactInfo()}
        </Layout>
      </Page.Content>
    </Page>
  );
};
```

### Accessibility examples

#### Heading structure

All pages must have a logical, descending heading structure that doesn't skip levels.

- Each page should have an `<h1>` as the main page title, and the first page heading. It should describe what the page is about.
- Use only one `<h1>` per page.
- Use `<h2>` for sections of content and for modal headings.
- Use `<h3>` for subsections.
- Don't skip heading levels.

When necessary, use the `as` prop to override the default heading tag without changing the design.

```jsx
<Page>
  <Page.Header title="H1" />
  <Page.Content>
    <Layout>
      <Cell span={8}>
        <Card stretchVertically={false}>
          <Card.Header
            title={
              <Heading size="medium" as="h2">
                Card title rendered as H2
              </Heading>
            }
          />
          <Card.Divider />
          <Card.Content>
            <Box height="120px" direction="vertical" gap="12px">
              <Heading size="tiny" as="h3">
                Card section title rendered as H3
              </Heading>
              <StorybookComponents.Placeholder height="24px" />
              <Heading size="tiny" as="h3">
                H3
              </Heading>
              <StorybookComponents.Placeholder height="24px" />
            </Box>
          </Card.Content>
        </Card>
      </Cell>
      <Cell span={4}>
        <Card stretchVertically={true}>
          <Card.Header
            title={
              <Heading size="medium" as="h2">
                H2
              </Heading>
            }
          />
          <Card.Divider />
          <Card.Content>
            <StorybookComponents.Placeholder height="120px" />
          </Card.Content>
        </Card>
      </Cell>
    </Layout>
  </Page.Content>
</Page>;
```

## Code

```jsx
import { Heading } from '@wix/design-system';
```

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `appearance` | `"H1" \| "H2" \| "H3" \| "H4" \| "H5" \| "H6"` | — | Sets the heading level, such as `'H1'`, which controls its visual style and HTML tag. It's ignored when `size` is provided. |
| `appendTo` | `null \| Element \| "window" \| "scrollParent" \| "viewport" \| "parent" \| Predicate` | — |  |
| `as` | `"object" \| "a" \| "abbr" \| "address" \| "area" \| "article" \| "aside" \| "audio" \| "b" \| "base" \| "bdi" \| "bdo" \| "blockquote" \| "body" \| "br" \| "button" \| "canvas" \| "caption" \| "cite" \| "code" \| "col" \| "colgroup" \| "data" \| "datalist" \| "dd" \| "del" \| "details" \| "dfn" \| "dialog" \| "div" \| "dl" \| "dt" \| "em" \| "embed" \| "fieldset" \| "figcaption" \| "figure" \| "footer" \| "form" \| "h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6" \| "head" \| "header" \| "hgroup" \| "hr" \| "html" \| "i" \| "iframe" \| "img" \| "input" \| "ins" \| "kbd" \| "label" \| "legend" \| "li" \| "link" \| "main" \| "map" \| "mark" \| "menu" \| "meta" \| "meter" \| "nav" \| "noscript" \| "ol" \| "optgroup" \| "option" \| "output" \| "p" \| "picture" \| "pre" \| "progress" \| "q" \| "rp" \| "rt" \| "ruby" \| "s" \| "samp" \| "search" \| "slot" \| "script" \| "section" \| "select" \| "small" \| "source" \| "span" \| "strong" \| "style" \| "sub" \| "summary" \| "sup" \| "table" \| "template" \| "tbody" \| "td" \| "textarea" \| "tfoot" \| "th" \| "thead" \| "time" \| "title" \| "tr" \| "track" \| "u" \| "ul" \| "var" \| "video" \| "wbr"` | — | Renders the heading as any other given HTML tag. |
| `children` | `ReactNode` | — | Renders any kind of content within a heading. Usually it's a text string. |
| `dataHook` | `string` | — | Applies a data-hook HTML attribute that can be used in the tests. |
| `disabled` | `boolean` | — |  |
| `ellipsis` | `boolean` | — | When true, text that is longer than it's container will be truncated to a single line followed by ellipsis. Otherwise the text will break into several lines. |
| `enterDelay` | `number` | — |  |
| `exitDelay` | `number` | — |  |
| `fixed` | `boolean` | — |  |
| `flip` | `boolean` | — |  |
| `id` | `string` | — | Identifies the element that labels or describes the text element. |
| `interactive` | `boolean` | — |  |
| `light` | `boolean` | — | Invert heading style so it can be used on a dark or image background. |
| `maxLines` | `number` | — | maxLines truncates text at a specific number of lines. |
| `maxWidth` | `string \| number \| string & {}` | — |  |
| `moveArrowTo` | `number` | — |  |
| `moveBy` | `Partial<{ x: number; y: number; }>` | — |  |
| `onEllipsisStateChange` | `(isActive: boolean) => void` | — | A callback fired when ellipsis state changes. |
| `onHide` | `() => void` | — |  |
| `onShow` | `() => void` | — |  |
| `placement` | `"right" \| "left" \| "top" \| "bottom" \| "auto" \| "auto-start" \| "auto-end" \| "top-start" \| "top-end" \| "right-start" \| "right-end" \| "bottom-end" \| "bottom-start" \| "left-end" \| "left-start"` | — |  |
| `showTooltip` | `boolean` | `true` | Shows a tooltip with the full text when the text is truncated. |
| `size` | `"small" \| "tiny" \| "medium" \| "large" \| "extraLarge" \| "extraTiny"` | — | Controls the heading's visual size and HTML tag appearance. HTML tag can be overridden with 'as' prop. |
| `textAlign` | `"center" \| "start"` | — |  |
| `zIndex` | `string & {} \| "-moz-initial" \| "inherit" \| "initial" \| "revert" \| "revert-layer" \| "unset" \| "auto" \| number & {}` | — |  |

## Testkit

Import the driver matching your test environment:

```jsx
// UniDriver
import { HeadingUniDriver } from '@wix/design-system/dist/testkit/unidriver';

// Vanilla
import { HeadingTestkit } from '@wix/design-system/dist/testkit';

// Puppeteer
import { HeadingTestkit } from '@wix/design-system/dist/testkit/puppeteer';

// Testing Library
import { HeadingTestkit } from '@wix/design-system/dist/testkit/testing-library';
```

### Driver methods

| Method | Description |
| --- | --- |
| `getText` | Gets text content |
| `getAppearance` | Gets heading appearance |
| `getSize` | Gets heading size |
| `getTagName` | Gets heading tag name |
| `isLight` | Checks whether heading is light |
| `isMasked` | Checks if heading has masking classNames |
| `getId` | Gets heading id |

## Changelog

- **1.340.0** (2026-10-21) — maintenance release, no component-specific changes
- **1.339.0** (2026-10-19) — maintenance release, no component-specific changes
- **1.338.0** (2026-10-15) — maintenance release, no component-specific changes
- **1.331.0** (2026-10-01) — maintenance release, no component-specific changes
- **1.330.0** (2026-09-28) — maintenance release, no component-specific changes
- **1.329.0** (2026-09-24) — maintenance release, no component-specific changes
- **1.325.0** (2026-09-17) — maintenance release, no component-specific changes
- **1.310.0** (2026-08-10) — maintenance release, no component-specific changes
- **1.292.0** (2026-06-22) — maintenance release, no component-specific changes
- **1.291.0** (2026-06-19) — maintenance release, no component-specific changes
- **1.278.0** (2026-05-08) — maintenance release, no component-specific changes
- **1.271.0** (2026-04-22) — maintenance release, no component-specific changes
- **1.266.0** (2026-04-07) — maintenance release, no component-specific changes
- **1.260.0** (2026-03-17) — maintenance release, no component-specific changes
- **1.254.0** (2026-02-03) — maintenance release, no component-specific changes
- **1.247.2** (2026-01-21) — maintenance release, no component-specific changes
- **1.220.2** (2025-10-06) — maintenance release, no component-specific changes
- **1.138.1** (2024-10-30) — maintenance release, no component-specific changes
- **1.115.0** (2024-07-17) — maintenance release, no component-specific changes
- **1.102.0** (2024-04-16) — maintenance release, no component-specific changes
- **1.99.0** (2024-03-29) — maintenance release, no component-specific changes
- **1.98.0** (2024-03-15) — maintenance release, no component-specific changes
- **1.97.0** (2024-02-26) — maintenance release, no component-specific changes
- **1.95.1** (2024-02-19) — maintenance release, no component-specific changes
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes