Element Selector Methods

The element selector constructor provides two groups of methods:

Filter Elements

The Filter Elements group contains methods that filter a matching set returned by a base selector.

nth(index)

Finds an element by its index in a matching set. The index parameter is zero-based. If index is negative, the index is counted from the end of a matching set.

For example:

  • nth(2) - Selects the third element.
  • nth(-1) - Selects the last element.

withText(text)

Filters a matching set by the specified text. Selects elements that contain this text. The text parameter is case-sensitive.

To filter elements by strict match, use the withExactText method.

withText(re)

Filters a matching set using the specified regular expression, for example, withText(/a[b-e]/).

withExactText(text)

Filters a matching set by the specified text. Selects elements whose text content strictly matches this text. The text parameter is case-sensitive.

To search for elements that contain a specific text, use the withText method.

withAttribute(attrName)

Finds elements that contain the specified attribute.

The Attribute Name parameter is a string or a regular expression.

For example, withAttribute('myAttr') selects elements that have the myAttr attribute. This attribute can have any value.

withAttribute(attrName, attrValue)

Finds elements that contain the specified attribute with the specified value.

The Attribute Name and Attribute Value parameters are strings or regular expressions.

For example:

  • withAttribute('attrName', 'foo') - Selects elements whose attrName attribute is set to foo. Does not match the otherAttr attribute, or the attrName attribute with the foobar value.

  • withAttribute(/[123]z/, /a[0-9]/) - Selects elements that have an attribute whose name matches the /[123]z/ regular expression. This attribute must have a value that matches the /a[0-9]/ regular expression. Matches the '1z' and '3z' attributes with the 'a0' and 'a7' values. Does not match the '4z' or '1b' attribute, as well as any attribute with the 'b0' or 'ab' value.

filterVisible()

Filters a matching set leaving only visible elements. These are elements that do not have the display: none or visibility: hidden CSS properties and have a non-zero width and height.

filterHidden()

Filters a matching set leaving only hidden elements. These are elements that have the display: none or visibility: hidden CSS property or a zero width or height.

filter(cssSelector)

Finds elements that match the specified CSS selector.

For example, filter('.someClass') selects elements that have the someClass class.

filter(filterFunction)

Filters elements using filterFunction. This function takes each element in a matching set and check if the element satisfies the specified conditions.

The function takes the following parameters:

Parameter Description
node The current DOM node.
idx The current node's index among other nodes in a matching set.
Note

You cannot use the following within the filter function:

The Search for Related Elements group contains methods that find related elements for elements returned by a base selector.

find

  • find(cssSelector) - Finds all descendants of all elements in a matching set and filters them by the specified CSS selector.

  • find(filterFunction) - Finds all descendants of all elements in a matching set and filters them using the filter function.

parent

  • parent() - Finds all parents of all elements in a matching set (the first element in the set will be the closest parent).

  • parent(index) - Finds all parents of all elements in a matching set and filters them by index (0 is the closest). If index is negative, the index is counted from the end of a matching set.

  • parent(cssSelector) - Finds all parents of all elements in a matching set and filters them by the specified CSS selector.

  • parent(filterFunction) - Finds all parents of all elements in a matching set and filters them using the filter function.

child

  • child() - Finds all child elements of all elements in a matching set.

  • child(index) - Finds all child elements of all elements in a matching set and filters them by index. The index parameter is zero-based. If index is negative, the index is counted from the end of a matching set.

  • child(cssSelector) - Finds all child elements of all elements in a matching set and filters them by the specified CSS selector.

  • child(filterFunction) - Finds all child elements of all elements in a matching set and filters them using the filter function.

sibling

  • sibling() - Finds all sibling elements of all elements in a matching set.

  • sibling(index) - Finds all sibling elements of all elements in a matching set and filters them by index. The index parameter is zero-based. If index is negative, the index is counted from the end of a matching set.

  • sibling(cssSelector) - Finds all sibling elements of all elements in a matching set and filters them by the specified CSS selector.

  • sibling(filterFunction) - Finds all sibling elements of all elements in a matching set and filters them using the filter function.

nextSibling

  • nextSibling() - Finds all succeeding sibling elements of all elements in a matching set.

  • nextSibling(index) - Finds all succeeding sibling elements of all elements in a matching set and filters them by index. The index parameter is zero-based. If index is negative, the index is counted from the end of a matching set.

  • nextSibling(cssSelector) - Finds all succeeding sibling elements of all elements in a matching set and filters them by cssSelector.

  • nextSibling(filterFunction) - Finds all succeeding sibling elements of all elements in a matching set and filters them using the filter function.

prevSibling

  • prevSibling() - Finds all preceding sibling elements of all elements in a matching set.

  • prevSibling(index) - Finds all preceding sibling elements of all elements in a matching set and filters them by index. The index parameter is zero-based. If index is negative, the index is counted from the end of a matching set.

  • prevSibling(cssSelector) - Finds all preceding sibling elements of all elements in a matching set and filters them by the specified CSS selector.

  • prevSibling(filterFunction) - Finds all preceding sibling elements of all elements in a matching set and filters them using the filter function.

Filter Elements Using Function

The Search for Related Elements methods allow you to filter a matching set using a filter function. The function takes each element in the matching set and checks if the element satisfies some conditions.

The function takes the following parameters.

Parameter Description
node The current matching node.
idx The current node's index among other matching nodes.
originNode The node whose parents/siblings/children is currently being iterated.

The following example demonstrates how to use a filter function in the find method.

Filter function

Note

You cannot use the following within the filter function: