Element.matches

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

Revision Content

{{ DomRef() }}

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 {{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
{{CompatVersionUnknown}} with the non-standard name webkitMatchesSelector
Feature Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Basic support {{CompatUnknown}} {{CompatGeckoMobile("1.9.2")}} {{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() }}</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 matchesSelector().</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>{{CompatVersionUnknown}} with the non-standard name <code>webkitMatchesSelector</code></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>{{CompatVersionUnknown}} 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")}}</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