Microsoft/TypeScript

DOM: `Element#matches()` incorrectly narrows types

Open

#63497 opened on May 20, 2026

View on GitHub
 (12 comments) (1 reaction) (0 assignees)TypeScript (48,455 stars) (6,726 forks)batch import
Domain: lib.d.tsHelp Wanted

Description

🔎 Search Terms

element matches narrow never

🕗 Version & Regression Information

  • This changed between versions 5.9.3 and 6.0.3

⏯ Playground Link

https://www.typescriptlang.org/play/?ts=6.0.3#code/CYUwxgNghgTiAEEQBd4iQWxAO2QLngAkAVAWQBkBRTHZAbgCgBCdELXAOgymTAAsQAZwAU8AOTBkY+AEp4AMnloanbrwEjxwYNJlA

💻 Code

declare let element: HTMLElement;
!element.matches( 'dt' ) && element.matches( 'dd' )

🙁 Actual behavior

element.matches( 'dd' ) throws a Property 'matches' does not exist on type 'never' compilation error.

🙂 Expected behavior

element.matches( 'dd' ) does not throw any error.

Additional information about the issue

element.matches( 'dt' ) uses the following overload:

matches<K extends keyof HTMLElementTagNameMap>(selectors: K): this is HTMLElementTagNameMap[K];

The return type of element.matches( 'dt' ) is then this is HTMLElementTagNameMap['dt'] that maps to this is HTMLElement.

Since this is HTMLElement:

  • When false, the type of element is HTMLElement (not narrowed further).
  • When false, the type of element is never.

Contributor guide

Tech stack
typescript
Domain
frontend
Issue type
bug
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
TypeScripttype predicatesHTMLElement
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
60
Research direction
Examine the type definition for Element.matches() in the TypeScript DOM lib (lib.dom.d.ts). The issue is that the type predicate `this is HTMLElementTagNameMap[K]` incorrectly narrows the type to `never` when the condition is false, leading to a compilation error. Investigate the overloaded signature and consider modifying the return type to properly narrow without producing `never`.