---
name: "Mojo::DOM::CSS"
section: "3pm"
platform: "linux"
package: "libmojolicious-perl"
version: "9.39+dfsg-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Mojo::DOM::CSS"
---

# Mojo::DOM::CSS(3pm)

CSS selector engine

## NAME

Mojo::DOM::CSS - CSS selector engine

## SYNOPSIS

```
  use Mojo::DOM::CSS;
  # Select elements from DOM tree
  my $css = Mojo::DOM::CSS->new(tree => $tree);
  my $elements = $css->select('h1, h2, h3');
```

## DESCRIPTION

Mojo::DOM::CSS is the CSS selector engine used by Mojo::DOM, based on the HTML Living Standard \<https://html.spec.whatwg.org\> and Selectors Level 3 \<https://www.w3.org/TR/css3-selectors/\>.

## SELECTORS

All CSS selectors that make sense for a standalone parser are supported.

### \*

Any element.

```
  my $all = $css->select('*');
```

### E

An element of type `"E"`.

```
  my $title = $css->select('title');
```

### E\[foo\]

An `"E"` element with a `"foo"` attribute.

```
  my $links = $css->select('a[href]');
```

### E\[foo="bar"\]

An `"E"` element whose `"foo"` attribute value is exactly equal to `"bar"`.

```
  my $case_sensitive = $css->select('input[type="hidden"]');
  my $case_sensitive = $css->select('input[type=hidden]');
```

### E\[foo="bar" i\]

An `"E"` element whose `"foo"` attribute value is exactly equal to any (ASCII-range) case-permutation of `"bar"`. Note that this selector is **EXPERIMENTAL** and might change without warning!

```
  my $case_insensitive = $css->select('input[type="hidden" i]');
  my $case_insensitive = $css->select('input[type=hidden i]');
  my $case_insensitive = $css->select('input[class~="foo" i]');
```

This selector is part of Selectors Level 4 \<https://dev.w3.org/csswg/selectors-4\>, which is still a work in progress.

### E\[foo="bar" s\]

An `"E"` element whose `"foo"` attribute value is exactly and case-sensitively equal to `"bar"`. Note that this selector is **EXPERIMENTAL** and might change without warning!

```
  my $case_sensitive = $css->select('input[type="hidden" s]');
```

This selector is part of Selectors Level 4 \<https://dev.w3.org/csswg/selectors-4\>, which is still a work in progress.

### E\[foo~="bar"\]

An `"E"` element whose `"foo"` attribute value is a list of whitespace-separated values, one of which is exactly equal to `"bar"`.

```
  my $foo = $css->select('input[class~="foo"]');
  my $foo = $css->select('input[class~=foo]');
```

### E\[foo^="bar"\]

An `"E"` element whose `"foo"` attribute value begins exactly with the string `"bar"`.

```
  my $begins_with = $css->select('input[name^="f"]');
  my $begins_with = $css->select('input[name^=f]');
```

### E\[foo$="bar"\]

An `"E"` element whose `"foo"` attribute value ends exactly with the string `"bar"`.

```
  my $ends_with = $css->select('input[name$="o"]');
  my $ends_with = $css->select('input[name$=o]');
```

### E\[foo\*="bar"\]

An `"E"` element whose `"foo"` attribute value contains the substring `"bar"`.

```
  my $contains = $css->select('input[name*="fo"]');
  my $contains = $css->select('input[name*=fo]');
```

### E\[foo\|="en"\]

An `"E"` element whose `"foo"` attribute has a hyphen-separated list of values beginning (from the left) with `"en"`.

```
  my $english = $css->select('link[hreflang|=en]');
```

### E:root

An `"E"` element, root of the document.

```
  my $root = $css->select(':root');
```

### E:nth-child(n)

An `"E"` element, the `"n-th"` child of its parent.

```
  my $third = $css->select('div:nth-child(3)');
  my $odd   = $css->select('div:nth-child(odd)');
  my $even  = $css->select('div:nth-child(even)');
  my $top3  = $css->select('div:nth-child(-n+3)');
```

### E:nth-last-child(n)

An `"E"` element, the `"n-th"` child of its parent, counting from the last one.

```
  my $third    = $css->select('div:nth-last-child(3)');
  my $odd      = $css->select('div:nth-last-child(odd)');
  my $even     = $css->select('div:nth-last-child(even)');
  my $bottom3  = $css->select('div:nth-last-child(-n+3)');
```

### E:nth-of-type(n)

An `"E"` element, the `"n-th"` sibling of its type.

```
  my $third = $css->select('div:nth-of-type(3)');
  my $odd   = $css->select('div:nth-of-type(odd)');
  my $even  = $css->select('div:nth-of-type(even)');
  my $top3  = $css->select('div:nth-of-type(-n+3)');
```

### E:nth-last-of-type(n)

An `"E"` element, the `"n-th"` sibling of its type, counting from the last one.

```
  my $third    = $css->select('div:nth-last-of-type(3)');
  my $odd      = $css->select('div:nth-last-of-type(odd)');
  my $even     = $css->select('div:nth-last-of-type(even)');
  my $bottom3  = $css->select('div:nth-last-of-type(-n+3)');
```

### E:first-child

An `"E"` element, first child of its parent.

```
  my $first = $css->select('div p:first-child');
```

### E:last-child

An `"E"` element, last child of its parent.

```
  my $last = $css->select('div p:last-child');
```

### E:first-of-type

An `"E"` element, first sibling of its type.

```
  my $first = $css->select('div p:first-of-type');
```

### E:last-of-type

An `"E"` element, last sibling of its type.

```
  my $last = $css->select('div p:last-of-type');
```

### E:only-child

An `"E"` element, only child of its parent.

```
  my $lonely = $css->select('div p:only-child');
```

### E:only-of-type

An `"E"` element, only sibling of its type.

```
  my $lonely = $css->select('div p:only-of-type');
```

### E:empty

An `"E"` element that has no children (including text nodes).

```
  my $empty = $css->select(':empty');
```

### E:any-link

Alias for "E:link". Note that this selector is **EXPERIMENTAL** and might change without warning! This selector is part of Selectors Level 4 \<https://dev.w3.org/csswg/selectors-4\>, which is still a work in progress.

### E:link

An `"E"` element being the source anchor of a hyperlink of which the target is not yet visited (`":link"`) or already visited (`":visited"`). Note that Mojo::DOM::CSS is not stateful, therefore `":any-link"`, `":link"` and `":visited"` yield exactly the same results.

```
  my $links = $css->select(':any-link');
  my $links = $css->select(':link');
  my $links = $css->select(':visited');
```

### E:visited

Alias for "E:link".

### E:scope

An `"E"` element being a designated reference element. Note that this selector is **EXPERIMENTAL** and might change without warning!

```
  my $scoped = $css->select('a:not(:scope > a)');
  my $scoped = $css->select('div :scope p');
  my $scoped = $css->select('~ p');
```

This selector is part of Selectors Level 4 \<https://dev.w3.org/csswg/selectors-4\>, which is still a work in progress.

### E:checked

A user interface element `"E"` which is checked (for instance a radio-button or checkbox).

```
  my $input = $css->select(':checked');
```

### E.warning

An `"E"` element whose class is "warning".

```
  my $warning = $css->select('div.warning');
```

### E#myid

An `"E"` element with `"ID"` equal to "myid".

```
  my $foo = $css->select('div#foo');
```

### E:not(s1, s2)

An `"E"` element that does not match either compound selector `"s1"` or compound selector `"s2"`. Note that support for compound selectors is **EXPERIMENTAL** and might change without warning!

```
  my $others = $css->select('div p:not(:first-child, :last-child)');
```

Support for compound selectors was added as part of Selectors Level 4 \<https://dev.w3.org/csswg/selectors-4\>, which is still a work in progress.

### E:is(s1, s2)

An `"E"` element that matches compound selector `"s1"` and/or compound selector `"s2"`. Note that this selector is **EXPERIMENTAL** and might change without warning!

```
  my $headers = $css->select(':is(section, article, aside, nav) h1');
```

This selector is part of Selectors Level 4 \<https://dev.w3.org/csswg/selectors-4\>, which is still a work in progress.

### E:has(rs1, rs2)

An `"E"` element, if either of the relative selectors `"rs1"` or `"rs2"`, when evaluated with `"E"` as the :scope elements, match an element. Note that this selector is **EXPERIMENTAL** and might change without warning!

```
  my $link = $css->select('a:has(> img)');
```

This selector is part of Selectors Level 4 \<https://dev.w3.org/csswg/selectors-4\>, which is still a work in progress. Also be aware that this feature is currently marked `"at-risk"`, so there is a high chance that it will get removed completely.

### E:text(string\_or\_regex)

An `"E"` element containing text content that substring matches `"string_or_regex"` case-insensitively or that regex matches `"string_or_regex"`. For regular expressions use the format `:text(/.../)`. Note that this selector is **EXPERIMENTAL** and might change without warning!

```
  # Substring match
  my $login = $css->select(':text(Log in)');
  # Regex match
  my $login = $css->select(':text(/Log ?in/)');
  # Regex match (case-insensitive)
  my $login = $css->select(':text(/(?i:Log ?in)/)');
```

This is a custom selector for Mojo::DOM and not part of any spec.

### A\|E

An `"E"` element that belongs to the namespace alias `"A"` from CSS Namespaces Module Level 3 \<https://www.w3.org/TR/css-namespaces-3/\>. Key/value pairs passed to selector methods are used to declare namespace aliases.

```
  my $elem = $css->select('lq|elem', lq => 'http://example.com/q-markup');
```

Using an empty alias searches for an element that belongs to no namespace.

```
  my $div = $c->select('|div');
```

### E F

An `"F"` element descendant of an `"E"` element.

```
  my $headlines = $css->select('div h1');
```

### E \> F

An `"F"` element child of an `"E"` element.

```
  my $headlines = $css->select('html > body > div > h1');
```

### E + F

An `"F"` element immediately preceded by an `"E"` element.

```
  my $second = $css->select('h1 + h2');
```

### E ~ F

An `"F"` element preceded by an `"E"` element.

```
  my $second = $css->select('h1 ~ h2');
```

### E, F, G

Elements of type `"E"`, `"F"` and `"G"`.

```
  my $headlines = $css->select('h1, h2, h3');
```

### E\[foo=bar\]\[bar=baz\]

An `"E"` element whose attributes match all following attribute selectors.

```
  my $links = $css->select('a[foo^=b][foo$=ar]');
```

## ATTRIBUTES

Mojo::DOM::CSS implements the following attributes.

### tree

```
  my $tree = $css->tree;
  $css     = $css->tree(['root']);
```

Document Object Model. Note that this structure should only be used very carefully since it is very dynamic.

## METHODS

Mojo::DOM::CSS inherits all methods from Mojo::Base and implements the following new ones.

### matches

```
  my $bool = $css->matches('head > title');
  my $bool = $css->matches('svg|line', svg => 'http://www.w3.org/2000/svg');
```

Check if first node in "tree" matches the CSS selector. Trailing key/value pairs can be used to declare xml namespace aliases.

### select

```
  my $results = $css->select('head > title');
  my $results = $css->select('svg|line', svg => 'http://www.w3.org/2000/svg');
```

Run CSS selector against "tree". Trailing key/value pairs can be used to declare xml namespace aliases.

### select\_one

```
  my $result = $css->select_one('head > title');
  my $result =
    $css->select_one('svg|line', svg => 'http://www.w3.org/2000/svg');
```

Run CSS selector against "tree" and stop as soon as the first node matched. Trailing key/value pairs can be used to declare xml namespace aliases.

## DEBUGGING

You can set the `"MOJO_DOM_CSS_DEBUG"` environment variable to get some advanced diagnostics information printed to `"STDERR"`.

```
  MOJO_DOM_CSS_DEBUG=1
```

## SEE ALSO

Mojolicious, Mojolicious::Guides, \<https://mojolicious.org\>.