Element.matches

  • Revision slug: Web/API/Element.matches
  • Revision title: Element.matches
  • Revision id: 509703
  • Created:
  • Creator: ziyunfei
  • Is current revision? No
  • Comment

Revision Content

{{ DomRef() }}{{seeCompatTable}}

Summary

Returns true if the element would be selected by the specified selector string; otherwise, returns false.

Most browsers implements this, prefixed, under the non-standard name matchesSelector().

Syntax

result = element.matches(selectorString) 
  • result holds the return value true or false.
  • selectorString is a string representing the selector to test.

Example

  <div id="foo">This is the element!</div>
  <script type="text/javascript">
    var el = document.getElementById("foo");
    if (el.matches("div")) {
      alert("Match!");
    }
  </script>

This will alert, since the element is indeed a {{ HTMLElement("div") }}.

Exceptions

SYNTAX_ERR
The specified selector string is invalid.

Specification

Specification Status Comment
{{SpecName('Selectors API Level 2', '#matches', 'Element.matches')}} {{Spec2('Selectors API Level 2')}} Initial definition.

Browser compatibility

{{CompatibilityTable}}

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support

{{CompatVersionUnknown}} with the non-standard name webkitMatchesSelector

<{{CompatChrome("34")}} matches

{{CompatGeckoDesktop("1.9.2")}} with the non-standard name mozMatchesSelector [1] 9.0 with the non-standard name msMatchesSelector 11.5 with the non-standard name oMatchesSelector
15.0 with the non-standard name webkitMatchesSelector
5.0 with the non-standard name webkitMatchesSelector
Feature Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Basic support {{CompatUnknown}} {{CompatGeckoMobile("1.9.2")}} with the non-standard name mozMatchesSelector [1] {{CompatUnknown}} {{CompatUnknown}} {{CompatUnknown}}

[1] Prior to Gecko 2.0, invalid selector strings caused false to be returned instead of throwing an exception.

Revision Source

<p>{{ DomRef() }}{{seeCompatTable}}</p>
<h2 id="Summary" name="Summary">Summary</h2>
<p>Returns <code>true</code> if the element would be selected by the specified selector string; otherwise, returns <code>false</code>.</p>
<div class="warning">
 <p>Most browsers implements this, prefixed, under the non-standard name <code>matchesSelector()</code>.</p>
</div>
<h2 id="Syntax" name="Syntax">Syntax</h2>
<pre class="syntaxbox">
<em>result</em> = <em>element</em>.matches(selectorString) 
</pre>
<ul>
 <li><code>result</code> holds the return value <code>true</code> or <code>false</code>.</li>
 <li><code>selectorString</code> is a string representing the selector to test.</li>
</ul>
<h2 id="Example" name="Example">Example</h2>
<pre>
  &lt;div id="foo"&gt;This is the element!&lt;/div&gt;
  &lt;script type="text/javascript"&gt;
    var el = document.getElementById("foo");
    if (el.matches("div")) {
      alert("Match!");
    }
  &lt;/script&gt;
</pre>
<p>This will alert, since the element is indeed a {{ HTMLElement("div") }}.</p>
<h2 id="Exceptions">Exceptions</h2>
<dl>
 <dt>
  <code>SYNTAX_ERR</code></dt>
 <dd>
  The specified selector string is invalid.</dd>
</dl>
<h2 id="Specification">Specification</h2>
<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>{{SpecName('Selectors API Level 2', '#matches', 'Element.matches')}}</td>
   <td>{{Spec2('Selectors API Level 2')}}</td>
   <td>Initial definition.</td>
  </tr>
 </tbody>
</table>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<p>{{CompatibilityTable}}</p>
<div id="compat-desktop">
 <table class="compat-table">
  <tbody>
   <tr>
    <th>Feature</th>
    <th>Chrome</th>
    <th>Firefox (Gecko)</th>
    <th>Internet Explorer</th>
    <th>Opera</th>
    <th>Safari (WebKit)</th>
   </tr>
   <tr>
    <td>Basic support</td>
    <td>
     <p>{{CompatVersionUnknown}} with the non-standard name <code>webkitMatchesSelector</code></p>
     <p><{{CompatChrome("34")}} <code>matches</code></p>
    </td>
    <td>{{CompatGeckoDesktop("1.9.2")}} with the non-standard name <code>mozMatchesSelector</code> [1]</td>
    <td>9.0 with the non-standard name <code>msMatchesSelector</code></td>
    <td>11.5 with the non-standard name <code>oMatchesSelector</code><br />
     15.0 with the non-standard name <code>webkitMatchesSelector</code></td>
    <td>5.0 with the non-standard name <code>webkitMatchesSelector</code></td>
   </tr>
  </tbody>
 </table>
</div>
<div id="compat-mobile">
 <table class="compat-table">
  <tbody>
   <tr>
    <th>Feature</th>
    <th>Android</th>
    <th>Firefox Mobile (Gecko)</th>
    <th>IE Phone</th>
    <th>Opera Mobile</th>
    <th>Safari Mobile</th>
   </tr>
   <tr>
    <td>Basic support</td>
    <td>{{CompatUnknown}}</td>
    <td>{{CompatGeckoMobile("1.9.2")}} with the non-standard name <code>mozMatchesSelector</code> [1]</td>
    <td>{{CompatUnknown}}</td>
    <td>{{CompatUnknown}}</td>
    <td>{{CompatUnknown}}</td>
   </tr>
  </tbody>
 </table>
</div>
<p>[1] Prior to Gecko 2.0, invalid selector strings caused <code>false</code> to be returned instead of throwing an exception.</p>
Revert to this revision