Title

The Title element displays headings based on the content hierarchy levels.

Text

In Figma, define the title text in the text </> property.

In code, put the text between the <qds-title> and </qds-title> tags:

Loading...

Live Editor

<qds-title>This is a title</qds-title>

Emphasize a few words in the title to catch the user's attention on the most significant information, as demonstrated in the feedback design patterns.

Emphasizing words

In Figma, select the words and apply the matching title-emphasized text style. You may also apply one of the feedback colors.

In code, wrap the words in <strong></strong> tags:

Loading...

Live Editor

<qds-title>
  <strong>8 items</strong> pending approval
</qds-title>

Set the feedback-color property to one of the feedback colors to apply

color to the emphasized words only:

Loading...

Live Editor

<qds-title feedback-color="information">
  <strong>8 items</strong> pending approval
</qds-title>

Kicker

Use the kicker property to set an optional kicker text above the title.

In Figma, enable the 🅵 kicker toggle to see the kicker property.

Loading...

Live Editor

<qds-title kicker="Documentation">Tutorials</qds-title>

Subtitle

Use the subtitle property to set an optional subtitle text above the title.

In Figma, enable the 🅵 subtitle toggle to see the subtitle property.

Loading...

Live Editor

<qds-title subtitle="Get started in minutes">Tutorials</qds-title>

Writing guidelines

• Title text is mandatory. Do not show only a kicker or a subtitle.
• Use sentence case only.
• Keep titles short. Omit nonessential words and avoid jargon.
• Do not add line breaks into title texts.
• Front-load headings with strong keywords. Emphasize them as necessary.

See this NNGroup article for additional guidelines.

Layer and level

The layer and level properties set the layer and level to which the title belongs. By default, the title component

Loading...

Live Editor

<qds-title layer="panel" level="root">
  This is a root panel title
</qds-title>

The level property sets the to which the title belongs. The section level is used by default.

Loading...

Live Editor

<qds-title layer="panel" level="subsection">
  This is a panel subsection title
</qds-title>

Important

See the table of allowed layer/level combinations to see how these properties can be combined.

Icon

Use the icon-name property to display an icon next to the title. Quartz will look into the default icon library unless you specify another library using the icon-library property.

In Figma, enable the 🅵 icon toggle to see the icon-name property. See the Usage > Icons instructions for more details.

Loading...

Live Editor

<qds-title icon-name="alarm-clock">Scheduled tasks</qds-title>

Layout

The <qds-title> component lays out its internal parts automatically.

For example, when displaying an icon, the kicker, title, and subtitle are automatically left-aligned (in left-to-right languages):

Loading...

Live Editor

<qds-title
  level="subsection"
  icon-name="alarm-clock"
  kicker="Custom workflow"
  subtitle="Assign them as soon as possible"
>
  <strong>3 unassigned tasks</strong> are overdue
</qds-title>

Multi-line texts also align nicely, for example, when a translation increases the length of the content or when the horizontal space is getting too small:

Loading...

Live Editor

<div class="qds-main-subsection w-[280px]">
  <qds-title
    level="subsection"
    icon-name="alarm-clock"
    kicker="Flux de travail personnalisé"
    subtitle="Assignez-les le plus rapidement possible"
  >
    <strong>3 tâches non assignées</strong> sont en retard
  </qds-title>
</div>

Make sure to balance kickers/subtitles between titles in multiple columns:

Loading...

Live Editor

<div class="qds-main-section qds-related flex-row items-stretch p-0">
  <div class="qds-main-subsection flex-1">
    <qds-title level="subsection" kicker="Kicker" subtitle="Subtitle">
      Title
    </qds-title>
    <p>Some text showing the impact of unbalanced kickers and subtitles.</p>
  </div>
  <div class="qds-main-subsection flex-1 hidden md:flex">
    <qds-title level="subsection" kicker="Kicker">
      Unbalanced subtitle
    </qds-title>
    <p>Some text showing the impact of unbalanced kickers and subtitles.</p>
  </div>
  <div class="qds-main-subsection flex-1 hidden xl:flex">
    <qds-title level="subsection" subtitle="Subtitle">
      Unbalanced kicker
    </qds-title>
    <p>Some text showing the impact of unbalanced kickers and subtitles.</p>
  </div>
</div>

Implementation tips

Setting HTML heading level

As recommended by the web standards, the <h1>-<h6> tags should be used to describe the semantic structure of the document, not to set visual styles of the headings.

The qds-title component enables this good practice by decoupling the visual hierarchy, defined by its layer and importance properties, from the semantic structure, defined by its tag property:

In the following example, as there is only one section on the screen, that section can use the h1 level, and its subsections can use the h2 level:

Loading...

Live Editor

<div class="qds-main-section qds-related items-stretch">
  <qds-title level="section" tag="h1">
    The unique section uses a h1 heading
  </qds-title>
  <div class="flex flex-row qds-related">
    <div class="qds-main-subsection flex-1">
      <qds-title level="subsection" tag="h2">
        This subsection uses a h2 heading
      </qds-title>
      <p>Some paragraph text.</p>
    </div>
    <div class="qds-main-subsection flex-1">
      <qds-title level="subsection" tag="h2">
        This subsection uses a h2 heading
      </qds-title>
      <p>Some paragraph text.</p>
    </div>
  </div>
</div>

In that other example, there are two sections on the screen, so they should use the h2 level, while their subsections use the h3 level:

Loading...

Live Editor

<div class="qds-main">
  <div class="qds-main-section qds-related items-stretch">
    <qds-title level="section" tag="h2">
      This first section uses a h2 heading
    </qds-title>
    <div class="flex flex-row qds-related">
      <div class="qds-main-subsection flex-1">
        <qds-title level="subsection" tag="h3">
          This subsection uses a h3 heading
        </qds-title>
        <p>Some paragraph text.</p>
      </div>
      <div class="qds-main-subsection flex-1">
        <qds-title level="subsection" tag="h3">
          This subsection uses a h3 heading
        </qds-title>
        <p>Some paragraph text.</p>
      </div>
    </div>
  </div>
  <div class="qds-main-section qds-related items-stretch">
    <qds-title level="section" tag="h2">
      This second section uses a h2 heading
    </qds-title>
    <div class="flex flex-row qds-related">
      <div class="qds-main-subsection flex-1">
        <qds-title level="subsection" tag="h3">
          This subsection uses a h3 heading
        </qds-title>
        <p>Some paragraph text.</p>
      </div>
      <div class="qds-main-subsection flex-1">
        <qds-title level="subsection" tag="h3">
          This subsection uses a h3 heading
        </qds-title>
        <p>Some paragraph text.</p>
      </div>
    </div>
  </div>
</div>

Custom width

Titles have a default size, depending on their type. Use the width CSS property as you usually do to set a custom width.

For example, you can use the flex-1 utility class from our Tailwind preset:

Loading...

Live Editor

<div class="qds-main-subsection">
  <div class="flex self-stretch items-center">
    <qds-title class="flex-1" level="subsection">
      This is a title
    </qds-title>
    <qds-button icon-name="alarm-clock" text="Remind me"></qds-button>
  </div>
</div>

Or you can use the w-full utility class for mobile display:

Loading...

Live Editor

<qds-title class="w-full" level="subsection">
  This is a title
</qds-title>

Importing

Note: if you're using the lazy loader to load Quartz components, you can ignore this section.

Import

To import this component from the public jsDeliver CDN using a JavaScript import:

import { defineCustomElementQdsTitle } from 'https://cdn.jsdelivr.net/npm/@quartzds/core@next+esm'
defineCustomElementQdsTitle()

Bundler

To import this component using a bundler:

import { defineCustomElementQdsTitle } from '@quartzds/core'
defineCustomElementQdsTitle()

Angular

To import this component as an Angular component:

import { QdsTitle } from '@quartzds/core-angular'

React

To import this component as a React component:

import { QdsTitle } from '@quartzds/core-react'

Vue

To import this component as a Vue component:

import { QdsTitle } from '@quartzds/core-vue'

Component reference

Properties

Attribute / PropertyTypeDescriptionDefault

alignment

"center" | "end" | "start" | undefined

The alignment of the title.

'start'

icon-library / iconLibrary

string

The name of a registered icon library.

'default'

icon-name / iconName

string | undefined

The name of the icon to render.

Available names depend on the icon library being used.

undefined

kicker

string | undefined

Text to display for the kicker.

undefined

layer

"accessory" | "main" | "navigation" | "panel" | "popup" | undefined

'main'

level

"root" | "section" | "subsection" | undefined

'section'

subtitle

string | undefined

Text to display for the subtitle.

undefined

tag

"h1" | "h2" | "h3" | "h4" | "h5" | "h6" | undefined

HTML tag to use to render the title.

'h2'

variant

"web-main-section-display" | "web-main-section-hero" | "web-main-subsection-card" | "web-promo" | undefined

The title's variant.

undefined