Package org.jsoup.select

# Class Elements

java.lang.Object
java.util.AbstractCollection<Element>
java.util.AbstractList<Element>
java.util.ArrayList<Element>
org.jsoup.select.Elements

All Implemented Interfaces:
  `Serializable`, `Cloneable`, `Iterable<Element>`, `Collection<Element>`, `List<Element>`, `RandomAccess`, `SequencedCollection<Element>`

public class Elements extends ArrayList<Element>
A list of `Element`s, with methods that act on every element in the list.

To get an `Elements` object, use the `Element.select(String)` method.

Author:
  Jonathan Hedley, jonathan@hedley.net
See Also:
  - Serialized Form

## Field Summary

### Fields inherited from class java.util.AbstractList

`modCount`

## Constructor Summary

Constructors
Constructor
Description
`Elements()`
`Elements(int initialCapacity)`
`Elements(Collection<Element> elements)`
`Elements(List<Element> elements)`
`Elements(Element... elements)`

## Method Summary

Modifier and Type
Method
Description
`Elements`
`addClass(String className)`
Add the class name to every matched element's `class` attribute.
`Elements`
`after(String html)`
Insert the supplied HTML after each matched element's outer HTML.
`Elements`
`append(String html)`
Add the supplied HTML to the end of each matched element's inner HTML.
`String`
`attr(String attributeKey)`
Get an attribute value from the first matched element that has the attribute.
`Elements`
`attr(String attributeKey, String attributeValue)`
Set an attribute on all matched elements.
`Elements`
`before(String html)`
Insert the supplied HTML before each matched element's outer HTML.
`Elements`
`clone()`
Creates a deep copy of these elements.
`List<Comment>`
`comments()`
Get `Comment` nodes that are direct child nodes of the selected elements.
`List<DataNode>`
`dataNodes()`
Get `DataNode` nodes that are direct child nodes of the selected elements.
`List<String>`
`eachAttr(String attributeKey)`
Get the attribute value for each of the matched elements.
`List<String>`
`eachText()`
Get the text content of each of the matched elements.
`Elements`
`empty()`
Empty (remove all child nodes from) each matched element.
`Elements`
`eq(int index)`
Get the nth matched element as an Elements object.
`Elements`
`filter(NodeFilter nodeFilter)`
Perform a depth-first filtering on each of the selected elements.
`Element`
`first()`
Get the first matched element.
`List<FormElement>`
`forms()`
Get the `FormElement` forms from the selected elements, if any.
`boolean`
`hasAttr(String attributeKey)`
Checks if any of the matched elements have this attribute defined.
`boolean`
`hasClass(String className)`
Determine if any of the matched elements have this class name set in their `class` attribute.
`boolean`
`hasText()`
Test if any matched Element has any text content, that is not just whitespace.
`String`
`html()`
Get the combined inner HTML of all matched elements.
`Elements`
`html(String html)`
Set the inner HTML of each matched element.
`boolean`
`is(String query)`
Test if any of the matched elements match the supplied query.
`Element`
`last()`
Get the last matched element.
`Elements`
`next()`
Get the immediate next element sibling of each element in this list.
`Elements`
`next(String query)`
Get the immediate next element sibling of each element in this list, filtered by the query.
`Elements`
`nextAll()`
Get each of the following element siblings of each element in this list.
`Elements`
`nextAll(String query)`
Get each of the following element siblings of each element in this list, that match the query.
`Elements`
`not(String query)`
Remove elements from this list that match the `Selector` query.
`String`
`outerHtml()`
Get the combined outer HTML of all matched elements.
`Elements`
`parents()`
Get all of the parents and ancestor elements of the matched elements.
`Elements`
`prepend(String html)`
Add the supplied HTML to the start of each matched element's inner HTML.
`Elements`
`prev()`
Get the immediate previous element sibling of each element in this list.
`Elements`
`prev(String query)`
Get the immediate previous element sibling of each element in this list, filtered by the query.
`Elements`
`prevAll()`
Get each of the previous element siblings of each element in this list.
`Elements`
`prevAll(String query)`
Get each of the previous element siblings of each element in this list, that match the query.
`Elements`
`remove()`
Remove each matched element from the DOM.
`Elements`
`removeAttr(String attributeKey)`
Remove an attribute from every matched element.
`Elements`
`removeClass(String className)`
Remove the class name from every matched element's `class` attribute, if present.
`Elements`
`select(String query)`
Find matching elements within this element list.
`Elements`
`tagName(String tagName)`
Update (rename) the tag name of each matched element.
`String`
`text()`
Get the combined text of all the matched elements.
`List<TextNode>`
`textNodes()`
Get `TextNode` nodes that are direct child nodes of the selected elements.
`Elements`
`toggleClass(String className)`
Toggle the class name on every matched element's `class` attribute.
`String`
`toString()`
Get the combined outer HTML of all matched elements.
`Elements`
`traverse(NodeVisitor nodeVisitor)`
Perform a depth-first traversal on each of the selected elements.
`Elements`
`unwrap()`
Removes the matched elements from the DOM, and moves their children up into their parents.
`String`
`val()`
Get the form element's value of the first matched element.
`Elements`
`val(String value)`
Set the form element's value in each of the matched elements.
`Elements`
`wrap(String html)`
Wrap the supplied HTML around each matched elements.

### Methods inherited from class java.util.ArrayList

`add, add, addAll, addAll, addFirst, addLast, clear, contains, ensureCapacity, equals, forEach, get, getFirst, getLast, hashCode, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, remove, remove, removeAll, removeFirst, removeIf, removeLast, removeRange, replaceAll, retainAll, set, size, sort, spliterator, subList, toArray, toArray, trimToSize`

### Methods inherited from class java.util.AbstractCollection

`containsAll`

### Methods inherited from class java.lang.Object

`finalize, getClass, notify, notifyAll, wait, wait, wait`

### Methods inherited from interface java.util.Collection

`parallelStream, stream, toArray`

### Methods inherited from interface java.util.List

`containsAll, reversed`

## Constructor Details

### Elements

public Elements()

### Elements

public Elements(int initialCapacity)

### Elements

public Elements(Collection<Element> elements)

### Elements

public Elements(List<Element> elements)

### Elements

public Elements(Element... elements)

## Method Details

### clone

public Elements clone()
Creates a deep copy of these elements.

Overrides:
  `clone` in class `ArrayList<Element>`
Returns:
  a deep copy

### attr

public String attr(String attributeKey)
Get an attribute value from the first matched element that has the attribute.

Parameters:
  `attributeKey` - The attribute key.
Returns:
  The attribute value from the first matched element that has the attribute.. If no elements were matched (isEmpty() == true), or if the no elements have the attribute, returns empty string.
See Also:
  - `hasAttr(String)`

### hasAttr

public boolean hasAttr(String attributeKey)
Checks if any of the matched elements have this attribute defined.

Parameters:
  `attributeKey` - attribute key
Returns:
  true if any of the elements have the attribute; false if none do.

### eachAttr

public List<String> eachAttr(String attributeKey)
Get the attribute value for each of the matched elements. If an element does not have this attribute, no value is included in the result set for that element.

Parameters:
  `attributeKey` - the attribute name to return values for. You can add the `abs:` prefix to the key to get absolute URLs from relative URLs, e.g.: `doc.select("a").eachAttr("abs:href")` .
Returns:
  a list of each element's attribute value for the attribute

### attr

public Elements attr(String attributeKey, String attributeValue)
Set an attribute on all matched elements.

Parameters:
  `attributeKey` - attribute key
  `attributeValue` - attribute value
Returns:
  this

### removeAttr

public Elements removeAttr(String attributeKey)
Remove an attribute from every matched element.

Parameters:
  `attributeKey` - The attribute to remove.
Returns:
  this (for chaining)

### addClass

public Elements addClass(String className)
Add the class name to every matched element's `class` attribute.

Parameters:
  `className` - class name to add
Returns:
  this

### removeClass

public Elements removeClass(String className)
Remove the class name from every matched element's `class` attribute, if present.

Parameters:
  `className` - class name to remove
Returns:
  this

### toggleClass

public Elements toggleClass(String className)
Toggle the class name on every matched element's `class` attribute.

Parameters:
  `className` - class name to add if missing, or remove if present, from every element.
Returns:
  this

### hasClass

public boolean hasClass(String className)
Determine if any of the matched elements have this class name set in their `class` attribute.

Parameters:
  `className` - class name to check for
Returns:
  true if any do, false if none do

### val

public String val()
Get the form element's value of the first matched element.

Returns:
  The form element's value, or empty if not set.
See Also:
  - `Element.val()`

### val

public Elements val(String value)
Set the form element's value in each of the matched elements.

Parameters:
  `value` - The value to set into each matched element
Returns:
  this (for chaining)

### text

public String text()
Get the combined text of all the matched elements.

Note that it is possible to get repeats if the matched elements contain both parent elements and their own children, as the Element.text() method returns the combined text of a parent and all its children.

Returns:
  string of all text: unescaped and no HTML.
See Also:
  - `Element.text()`
  - `eachText()`

### hasText

public boolean hasText()
Test if any matched Element has any text content, that is not just whitespace.

Returns:
  true if any element has non-blank text content.
See Also:
  - `Element.hasText()`

### eachText

public List<String> eachText()
Get the text content of each of the matched elements. If an element has no text, then it is not included in the result.

Returns:
  A list of each matched element's text content.
See Also:
  - `Element.text()`
  - `Element.hasText()`
  - `text()`

### html

public String html()
Get the combined inner HTML of all matched elements.

Returns:
  string of all element's inner HTML.
See Also:
  - `text()`
  - `outerHtml()`

### outerHtml

public String outerHtml()
Get the combined outer HTML of all matched elements.

Returns:
  string of all element's outer HTML.
See Also:
  - `text()`
  - `html()`

### toString

public String toString()
Get the combined outer HTML of all matched elements. Alias of `outerHtml()`.

Overrides:
  `toString` in class `AbstractCollection<Element>`
Returns:
  string of all element's outer HTML.
See Also:
  - `text()`
  - `html()`

### tagName

public Elements tagName(String tagName)
Update (rename) the tag name of each matched element. For example, to change each `<i>` to a `<em>`, do `doc.select("i").tagName("em");`

Parameters:
  `tagName` - the new tag name
Returns:
  this, for chaining
See Also:
  - `Element.tagName(String)`

### html

public Elements html(String html)
Set the inner HTML of each matched element.

Parameters:
  `html` - HTML to parse and set into each matched element.
Returns:
  this, for chaining
See Also:
  - `Element.html(String)`

### prepend

public Elements prepend(String html)
Add the supplied HTML to the start of each matched element's inner HTML.

Parameters:
  `html` - HTML to add inside each element, before the existing HTML
Returns:
  this, for chaining
See Also:
  - `Element.prepend(String)`

### append

public Elements append(String html)
Add the supplied HTML to the end of each matched element's inner HTML.

Parameters:
  `html` - HTML to add inside each element, after the existing HTML
Returns:
  this, for chaining
See Also:
  - `Element.append(String)`

### before

public Elements before(String html)
Insert the supplied HTML before each matched element's outer HTML.

Parameters:
  `html` - HTML to insert before each element
Returns:
  this, for chaining
See Also:
  - `Element.before(String)`

### after

public Elements after(String html)
Insert the supplied HTML after each matched element's outer HTML.

Parameters:
  `html` - HTML to insert after each element
Returns:
  this, for chaining
See Also:
  - `Element.after(String)`

### wrap

public Elements wrap(String html)
Wrap the supplied HTML around each matched elements. For example, with HTML `<p><b>This</b> is <b>Jsoup</b></p>`, `doc.select("b").wrap("<i></i>");` becomes `<p><i><b>This</b></i> is <i><b>jsoup</b></i></p>`

Parameters:
  `html` - HTML to wrap around each element, e.g. `<div class="head"></div>`. Can be arbitrarily deep.
Returns:
  this (for chaining)
See Also:
  - `Element.wrap(java.lang.String)`

### unwrap

public Elements unwrap()
Removes the matched elements from the DOM, and moves their children up into their parents. This has the effect of dropping the elements but keeping their children.

This is useful for e.g removing unwanted formatting elements but keeping their contents.

E.g. with HTML:

`<div><font>One</font> <font><a href="/">Two</a></font></div>`

`doc.select("font").unwrap();`

HTML = `<div>One <a href="/">Two</a></div>`

Returns:
  this (for chaining)
See Also:
  - `Node.unwrap()`

### empty

public Elements empty()
Empty (remove all child nodes from) each matched element. This is similar to setting the inner HTML of each element to nothing.

E.g. HTML: `<div><p>Hello <b>there</b></p> <p>now</p></div>`
`doc.select("p").empty();`
HTML = `<div><p></p> <p></p></div>`

Returns:
  this, for chaining
See Also:
  - `Element.empty()`
  - `remove()`

### remove

public Elements remove()
Remove each matched element from the DOM. This is similar to setting the outer HTML of each element to nothing.

E.g. HTML: `<div><p>Hello</p> <p>there</p> <img /></div>`
`doc.select("p").remove();`
HTML = `<div> <img /></div>`

Note that this method should not be used to clean user-submitted HTML; rather, use `Cleaner` to clean HTML.

Returns:
  this, for chaining
See Also:
  - `Element.empty()`
  - `empty()`

### select

public Elements select(String query)
Find matching elements within this element list.

Parameters:
  `query` - A `Selector` query
Returns:
  the filtered list of elements, or an empty list if none match.

### not

public Elements not(String query)
Remove elements from this list that match the `Selector` query.

E.g. HTML: `<div class=logo>One</div> <div>Two</div>`
`Elements divs = doc.select("div").not(".logo");`
Result: `divs: [<div>Two</div>]`

Parameters:
  `query` - the selector query whose results should be removed from these elements
Returns:
  a new elements list that contains only the filtered results

### eq

public Elements eq(int index)
Get the nth matched element as an Elements object.

See also `ArrayList.get(int)` to retrieve an Element.

Parameters:
  `index` - the (zero-based) index of the element in the list to retain
Returns:
  Elements containing only the specified element, or, if that element did not exist, an empty list.

### is

public boolean is(String query)
Test if any of the matched elements match the supplied query.

Parameters:
  `query` - A selector
Returns:
  true if at least one element in the list matches the query.

### next

public Elements next()
Get the immediate next element sibling of each element in this list.

Returns:
  next element siblings.

### next

public Elements next(String query)
Get the immediate next element sibling of each element in this list, filtered by the query.

Parameters:
  `query` - CSS query to match siblings against
Returns:
  next element siblings.

### nextAll

public Elements nextAll()
Get each of the following element siblings of each element in this list.

Returns:
  all following element siblings.

### nextAll

public Elements nextAll(String query)
Get each of the following element siblings of each element in this list, that match the query.

Parameters:
  `query` - CSS query to match siblings against
Returns:
  all following element siblings.

### prev

public Elements prev()
Get the immediate previous element sibling of each element in this list.

Returns:
  previous element siblings.

### prev

public Elements prev(String query)
Get the immediate previous element sibling of each element in this list, filtered by the query.

Parameters:
  `query` - CSS query to match siblings against
Returns:
  previous element siblings.

### prevAll

public Elements prevAll()
Get each of the previous element siblings of each element in this list.

Returns:
  all previous element siblings.

### prevAll

public Elements prevAll(String query)
Get each of the previous element siblings of each element in this list, that match the query.

Parameters:
  `query` - CSS query to match siblings against
Returns:
  all previous element siblings.

### parents

public Elements parents()
Get all of the parents and ancestor elements of the matched elements.

Returns:
  all of the parents and ancestor elements of the matched elements

### first

@Nullable public Element first()
Get the first matched element.

Returns:
  The first matched element, or `null` if contents is empty.

### last

@Nullable public Element last()
Get the last matched element.

Returns:
  The last matched element, or `null` if contents is empty.

### traverse

public Elements traverse(NodeVisitor nodeVisitor)
Perform a depth-first traversal on each of the selected elements.

Parameters:
  `nodeVisitor` - the visitor callbacks to perform on each node
Returns:
  this, for chaining

### filter

public Elements filter(NodeFilter nodeFilter)
Perform a depth-first filtering on each of the selected elements.

Parameters:
  `nodeFilter` - the filter callbacks to perform on each node
Returns:
  this, for chaining

### forms

public List<FormElement> forms()
Get the `FormElement` forms from the selected elements, if any.

Returns:
  a list of `FormElement`s pulled from the matched elements. The list will be empty if the elements contain no forms.

### comments

public List<Comment> comments()
Get `Comment` nodes that are direct child nodes of the selected elements.

Returns:
  Comment nodes, or an empty list if none.

### textNodes

public List<TextNode> textNodes()
Get `TextNode` nodes that are direct child nodes of the selected elements.

Returns:
  TextNode nodes, or an empty list if none.

### dataNodes

public List<DataNode> dataNodes()
Get `DataNode` nodes that are direct child nodes of the selected elements. DataNode nodes contain the content of tags such as `script`, `style` etc and are distinct from `TextNode`s.

Returns:
  Comment nodes, or an empty list if none.