Heading

Components/Typography

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

Overview

Copy

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).

Copy

Light

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

Copy

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.

Copy

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.

Copy

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.

Copy

Common use case examples

Content hierarchy

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

Copy

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.

Copy

Code

Copy

Props

NameTypeDefaultDescription
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.
appendTonull | 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.
childrenReactNode—Renders any kind of content within a heading. Usually it's a text string.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
disabledboolean—
ellipsisboolean—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.
enterDelaynumber—
exitDelaynumber—
fixedboolean—
flipboolean—
idstring—Identifies the element that labels or describes the text element.
interactiveboolean—
lightboolean—Invert heading style so it can be used on a dark or image background.
maxLinesnumber—maxLines truncates text at a specific number of lines.
maxWidthstring | number | string & {}—
moveArrowTonumber—
moveByPartial<{ 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"—
showTooltipbooleantrueShows 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"—
zIndexstring & {} | "-moz-initial" | "inherit" | "initial" | "revert" | "revert-layer" | "unset" | "auto" | number & {}—

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
getTextGets text content
getAppearanceGets heading appearance
getSizeGets heading size
getTagNameGets heading tag name
isLightChecks whether heading is light
isMaskedChecks if heading has masking classNames
getIdGets 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

Last updated: 30 October 2026

Did this help?