angular/components · warning

A list item line can only be used if there is a list item…

Error message

A list item line can only be used if there is a list item title.

What it means

A `matListItemLine` (secondary line) only makes sense when the item also has a title. When `sanityCheckListItemContent` (called from `_updateItemLines`) finds zero titles but one or more lines, it warns in dev mode because the line has no primary content to belong to and the item renders incorrectly.

Solutions

1. Add a `<span matListItemTitle>` as the primary content of the item.
2. If the text was meant to be the title, mark it with `matListItemTitle` instead of `matListItemLine`.
3. Remove the orphan line if the item should only show a single line of text.

Example fix

<!-- before -->
<mat-list-item>
  <span matListItemLine>Secondary info</span>
</mat-list-item>

<!-- after -->
<mat-list-item>
  <span matListItemTitle>Primary</span>
  <span matListItemLine>Secondary info</span>
</mat-list-item>

if (item.querySelector('[matListItemLine]') && !item.querySelector('[matListItemTitle]')) {
  console.warn('List item line requires a title.');
}

When it happens

Trigger: A list item with `<span matListItemLine>` (or legacy `matLine`) content but no `matListItemTitle`, or relying on unscoped text as an implicit title while explicitly marking only lines.

Common situations: Migrating old `mat-list-item` markup that used bare text plus `matLine` spans to the new title/line directives without adding a title; deleting the title element during a refactor.

Related errors

• A list item can have at maximum three lines.
• A list item cannot have multiple titles.
• A list item cannot have wrapping content without a title.
• A drawer was already declared for 'position=
• A hint was already declared for 'align="start"'.

AI-assisted analysis of angular/components@0411926e7d (2026-08-31). Data as JSON: /api/errors/1fe3e57bd6395df8. Report an issue: GitHub.

Appendix: source

Thrown at src/material/list/list-base.ts:337

  }
}

/**
 * Sanity checks the configuration of the list item with respect to the amount
 * of lines, whether there is a title, or if there is unscoped text content.
 *
 * The checks are extracted into a top-level function that can be dead-code
 * eliminated by Terser or other optimizers in production mode.
 */
function sanityCheckListItemContent(item: MatListItemBase) {
  const numTitles = item._titles!.length;
  const numLines = item._lines!.length;

  if (numTitles > 1) {
    console.warn('A list item cannot have multiple titles.');
  }
  if (numTitles === 0 && numLines > 0) {
    console.warn('A list item line can only be used if there is a list item title.');
  }
  if (
    numTitles === 0 &&
    item._hasUnscopedTextContent &&
    item._explicitLines !== null &&
    item._explicitLines > 1
  ) {
    console.warn('A list item cannot have wrapping content without a title.');
  }
  if (numLines > 2 || (numLines === 2 && item._hasUnscopedTextContent)) {
    console.warn('A list item can have at maximum three lines.');
  }
}

View on GitHub (pinned to 0411926e7d)