@m3e/heading

The m3e-heading component provides expressive, accessible headings for pages and sections, supporting display, headline, title, and label variants in multiple sizes. It applies Material 3 typographic tokens for font size, weight, line height, and letter spacing, ensuring visual hierarchy and clarity.

This package is part of M3E monorepo, a unified suite of Material 3 web components. Explore the docs to see them in action.

📦 Installation

npm install @m3e/heading

💻 Editor Integration

This package includes a Custom Elements Manifest to support enhanced editor tooling and developer experience.

Visual Studio Code

To enable autocomplete and hover documentation for @m3e/heading, install the Custom Elements Manifest Language Server extension. It will automatically detect the manifest bundled with this package and surface tag names, attributes, slots, and events in supported files.

Alternately, you can explicitly reference the html-custom-data.json and css-custom-data.json in your workspace settings:

{
  "html.customData": ["./node_modules/@m3e/heading/dist/html-custom-data.json"],
  "css.customData": ["./node_modules/@m3e/heading/dist/css-custom-data.json"]
}

🚀 Native Module Support

This package uses JavaScript Modules. To use it directly in a browser without a bundler, use a module script similar to the following.

<script type="module" src="/node_modules/@m3e/heading/dist/index.js"></script>

In addition, you must use an import map to include dependencies.

<script type="importmap">
  {
    "imports": {
      "lit": "https://cdn.jsdelivr.net/npm/[email protected]/+esm",
      "@m3e/core": "/node_modules/@m3e/core/dist/index.js"
    }
  }
</script>

For production, use index.min.js for faster load times.

🗂️ Elements

• m3e-heading — A heading to a page or section.

🧪 Examples

The following example illustrates use of the m3e-heading to present each variant and size.

<m3e-heading variant="display" size="large">Display Large</m3e-heading>
<m3e-heading variant="display" size="medium">Display Medium</m3e-heading>
<m3e-heading variant="display" size="small">Display Small</m3e-heading>
<m3e-heading variant="headline" size="large">Headline Large</m3e-heading>
<m3e-heading variant="headline" size="medium">Headline Medium</m3e-heading>
<m3e-heading variant="headline" size="small">Headline Small</m3e-heading>
<m3e-heading variant="title" size="large">Title Large</m3e-heading>
<m3e-heading variant="title" size="medium">Title Medium</m3e-heading>
<m3e-heading variant="title" size="small">Title Small</m3e-heading>
<m3e-heading variant="label" size="large">Label Large</m3e-heading>
<m3e-heading variant="label" size="medium">Label Medium</m3e-heading>
<m3e-heading variant="label" size="small">Label Small</m3e-heading>

The next example illustrates use of the level attribute to designate the accessibility level of a heading. When specified, ARIA role="heading" is applied and the level is propagated to aria-level.

<m3e-heading variant="headline" size="large" level="1">Page title</m3e-heading>

📖 API Reference

This section details the attributes and slots available for the m3e-heading component.

⚙️ Attributes

| Attribute | Type | Default | Description | | ------------ | ----------------------------------------------------- | ----------- | ------------------------------------------------- | | emphasized | boolean | false | Whether the heading uses an emphasized typescale. | | variant | "display" | "headline" | "title" | "label" | "display" | The appearance variant of the heading. | | size | "small" | "medium" | "large" | "medium" | The size of the heading. | | level | 1 | 2 | 3 | 4 | 5 | 6 | | The accessibility level of the heading. |

🧩 Slots

| Slot | Description | | ----------- | ----------------------------------- | | (default) | Renders the content of the heading. |

🤝 Contributing

See the root monorepo CONTRIBUTING.md for guidelines on contributing to this package.

📄 License

This package is licensed under the MIT License.