Class Element

A HTML element consists of a tag name, attributes, and child nodes (including text nodes and other elements).

Inheritance

System.Object

Node

Element

Document

FormElement

Namespace: Supremes.Nodes

Assembly: Supremes.dll

Syntax

public class Element : Node

Remarks

From an Element, you can extract data, traverse the node graph, and manipulate the HTML.

Properties

Children

Get this element's child elements.

Declaration

public Elements Children { get; }

Property Value

Type	Description
Elements	child elements. If this element has no children, returns an empty list.

Remarks

This is effectively a filter on ChildNodes to get Element nodes.

ClassName

Gets the literal value of this element's "class" attribute, which may include multiple class names, space separated.

Declaration

public string ClassName { get; }

Property Value

Type	Description
System.String	The literal class attribute, or empty string if no class attribute set.

Remarks

(E.g. on <div class="header gray"> returns, "header gray")

ClassNames

Get or Set all of the element's class names.

Declaration

public ICollection<string> ClassNames { get; set; }

Property Value

Type	Description
ICollection<System.String>	the new set of classes

Remarks

E.g. on element <div class="header gray">, this property returns a set of two elements "header", "gray". Note that modifications to this set are not pushed to the backing class attribute; use the ClassNames method to persist them.

if you want to use fluent API, write using Supremes.Fluent;.

CssSelector

Get a CSS selector that will uniquely select this element.

Declaration

public string CssSelector { get; }

Property Value

Type	Description
System.String	the CSS Path that can be used to retrieve the element in a selector.

Remarks

If the element has an ID, returns #id; otherwise returns the parent (if any) CSS selector, followed by '>', followed by a unique selector for the element (tag.class.class:nth-child(n)).

Data

Get the combined data of this element.

Declaration

public string Data { get; }

Property Value

Type	Description
System.String	the data, or empty string if none

Remarks

Data is e.g. the inside of a script tag.

Declaration

public IReadOnlyList<DataNode> DataNodes { get; }

Property Value

Type	Description
IReadOnlyList<DataNode>	child data nodes. If this element has no data nodes, returns an empty list.

Remarks

The list is unmodifiable but the data nodes may be manipulated.

This is effectively a filter on ChildNodes to get Data nodes.

Dataset

Get this element's HTML5 custom data attributes.

Declaration

public IDictionary<string, string> Dataset { get; }

Property Value

Type	Description
IDictionary<System.String, System.String>	a map of `key=value` custom data attributes.

Remarks

Each attribute in the element that has a key starting with "data-" is included the dataset.

E.g., the element <div data-package="jsoup" data-language="Java" class="group">... has the dataset package=jsoup, language=java .

This map is a filtered view of the element's attribute map. Changes to one map (add, remove, update) are reflected in the other map.

You can find elements that have data attributes using the [^data-] attribute key prefix selector.

ElementSiblingIndex

Get the list index of this element in its element sibling list.

Declaration

public int ElementSiblingIndex { get; }

Property Value

Type	Description
System.Int32	position in element sibling list

Remarks

I.e. if this is the first element sibling, returns 0.

FirstElementSibling

Gets the first element sibling of this element.

Declaration

public Element FirstElementSibling { get; }

Property Value

Type	Description
Element	the first sibling that is an element (aka the parent's first element child)

HasText

Test if this element has any text content (that is not just whitespace).

Declaration

public bool HasText { get; }

Property Value

Type	Description
System.Boolean	true if element has non-blank text content.

Html

Get Or Set the element's inner HTML.

Declaration

public string Html { get; set; }

Property Value

Type	Description
System.String	HTML to parse and set into this element

Remarks

when get on a <div> with one empty <p>, would return <p></p>. (Whereas OuterHtml would return <div><p></p></div>.)

when set, clears the existing HTML first.

if you want to use fluent API, write using Supremes.Fluent;.

Id

Get the id attribute of this element.

Declaration

public string Id { get; }

Property Value

Type	Description
System.String	The id attribute, if present, or an empty string if not.

IsBlock

Test if this element is a block-level element.

Declaration

public bool IsBlock { get; }

Property Value

Type	Description
System.Boolean	true if block, false if not (and thus inline)

Remarks

(E.g. <div> == true or an inline element <p> == false ).

LastElementSibling

Gets the last element sibling of this element

Declaration

public Element LastElementSibling { get; }

Property Value

Type	Description
Element	the last sibling that is an element (aka the parent's last element child)

NextElementSibling

Gets the next sibling element of this element.

Declaration

public Element NextElementSibling { get; }

Property Value

Type	Description
Element	the next element, or null if there is no next element

Remarks

E.g., if a div contains two p s, the NextElementSibling of the first p is the second p .

This is similar to NextSibling , but specifically finds only Elements

OwnText

Gets the text owned by this element only; does not get the combined text of all children.

Declaration

public string OwnText { get; }

Property Value

Type	Description
System.String	unencoded text, or empty string if none.

Remarks

For example, given HTML <p>Hello <b>there</b> now!</p> , p.OwnText returns "Hello now!" , whereas p.Text returns "Hello there now!" . Note that the text within the b element is not returned, as it is not a direct child of the p element.

Parent

Gets this element's parent element.

Declaration

public Element Parent { get; }

Property Value

Type	Description
Element

Parents

Get this element's parent and ancestors, up to the document root.

Declaration

public Elements Parents { get; }

Property Value

Type	Description
Elements	this element's stack of parents, closest first.

PreviousElementSibling

Gets the previous element sibling of this element.

Declaration

public Element PreviousElementSibling { get; }

Property Value

Type	Description
Element	the previous element, or null if there is no previous element

SiblingElements

Get sibling elements.

Declaration

public Elements SiblingElements { get; }

Property Value

Type	Description
Elements	sibling elements

Remarks

If the element has no sibling elements, returns an empty list. An element is not a sibling of itself, so will not be included in the returned list.

Tag

Get the Tag for this element.

Declaration

public Tag Tag { get; }

Property Value

Type	Description
Tag	the tag object

TagName

Get or Set the name of the tag for this element.

Declaration

public string TagName { get; set; }

Property Value

Type	Description
System.String	the new tag name

Remarks

E.g. div

For example, convert a <span> to a <div> with el.TagName = "div"; .

if you want to use fluent API, write using Supremes.Fluent;.

Text

Get or Set the combined text of this element and all its children.

Declaration

public virtual string Text { get; set; }

Property Value

Type	Description
System.String	unencoded text

Remarks

when get, whitespace is normalized and trimmed.

For example, given HTML <p>Hello <b>there</b> now! </p>, p.Text returns "Hello there now!"

when set, any existing contents (text or elements) will be cleared.

Declaration

public IReadOnlyList<TextNode> TextNodes { get; }

Property Value

Type	Description
IReadOnlyList<TextNode>	child text nodes. If this element has no text nodes, returns an empty list. For example, with the input HTML: `<p>One <span>Two</span> Three <br /> Four</p>` with the `p` element selected: `p.Text` = `"One Two Three Four"` `p.OwnText` = `"One Three Four"` `p.Children` = `Elements[<span>, <br />]` `p.ChildNodes` = `List<Node>["One ", <span>, " Three ", <br />, " Four"]` `p.TextNodes` = `List<TextNode>["One ", " Three ", " Four"]`

Remarks

The list is unmodifiable but the text nodes may be manipulated.

This is effectively a filter on ChildNodes to get Text nodes.

Val

Get or Set the value of a form element (input, textarea, etc).

Declaration

public string Val { get; set; }

Property Value

Type	Description
System.String	value to set

Remarks

if you want to use fluent API, write using Supremes.Fluent;.

Methods

AddClass(String)

Add a class name to this element's class attribute.

Declaration

public Element AddClass(string className)

Parameters

Type	Name	Description
System.String	className	class name to add

Returns

Type	Description
Element	this element

After(Node)

Insert the specified node into the DOM after this node (as a following sibling).

Declaration

public override Node After(Node node)

Parameters

Type	Name	Description
Node	node	to add after this element

Returns

Type	Description
Node	this element, for chaining

Overrides

Node.After(Node)

After(String)

Insert the specified HTML into the DOM after this element (as a following sibling).

Declaration

public override Node After(string html)

Parameters

Type	Name	Description
System.String	html	HTML to add after this element

Returns

Type	Description
Node	this element, for chaining

Overrides

Node.After(String)

Append(String)

Add inner HTML to this element.

Declaration

public Element Append(string html)

Parameters

Type	Name	Description
System.String	html	HTML to add inside this element, after the existing HTML

Returns

Type	Description
Element	this element

Remarks

The supplied HTML will be parsed, and each node appended to the end of the children.

AppendChild(Node)

Add a node child node to this element.

Declaration

public Element AppendChild(Node child)

Parameters

Type	Name	Description
Node	child	node to add.

Returns

Type	Description
Element	this element, so that you can add more child nodes or elements.

AppendElement(String)

Create a new element by tag name, and add it as the last child.

Declaration

public Element AppendElement(string tagName)

Parameters

Type	Name	Description
System.String	tagName	the name of the tag (e.g. `div` ).

Returns

Type	Description
Element	the new element, to allow you to add content to it, e.g.: `parent.AppendElement("h1").Attr("id", "header").Text("Welcome");`

AppendText(String)

Create and append a new TextNode to this element.

Declaration

public Element AppendText(string text)

Parameters

Type	Name	Description
System.String	text	the unencoded text to add

Returns

Type	Description
Element	this element

Before(Node)

Insert the specified node into the DOM before this node (as a preceding sibling).

Declaration

public override Node Before(Node node)

Parameters

Type	Name	Description
Node	node	to add before this element

Returns

Type	Description
Node	this Element, for chaining

Overrides

Node.Before(Node)

Before(String)

Insert the specified HTML into the DOM before this element (as a preceding sibling).

Declaration

public override Node Before(string html)

Parameters

Type	Name	Description
System.String	html	HTML to add before this element

Returns

Type	Description
Node	this element, for chaining

Overrides

Node.Before(String)

Child(Int32)

Get a child element of this element, by its 0-based index number.

Declaration

public Element Child(int index)

Parameters

Type	Name	Description
System.Int32	index	the index number of the element to retrieve

Returns

Type	Description
Element	the child element, if it exists, otherwise throws an `IndexOutOfBoundsException`

Remarks

Note that an element can have both mixed Nodes and Elements as children. This method inspects a filtered list of children that are elements, and the index is based on that filtered list.

Empty()

Remove all of the element's child nodes.

Declaration

public Element Empty()

Returns

Type	Description
Element	this element

Remarks

Any attributes are left as-is.

Equals(Object)

Compares two Element instances for equality.

Declaration

public override bool Equals(object o)

Parameters

Type	Name	Description
System.Object	o

Returns

Type	Description
System.Boolean

Overrides

Node.Equals(Object)

GetAllElements()

Find all elements under this element (including self, and children of children).

Declaration

public Elements GetAllElements()

Returns

Type	Description
Elements	all elements

GetElementById(String)

Find an element by ID, including or under this element.

Declaration

public Element GetElementById(string id)

Parameters

Type	Name	Description
System.String	id	The ID to search for.

Returns

Type	Description
Element	The first matching element by ID, starting with this element, or null if none found.

Remarks

Note that this finds the first matching ID, starting with this element. If you search down from a different starting point, it is possible to find a different element by ID. For unique element by ID within a Document, use GetElementById(String)

GetElementsByAttribute(String)

Find elements that have a named attribute set.

Declaration

public Elements GetElementsByAttribute(string key)

Parameters

Type	Name	Description
System.String	key	name of the attribute, e.g. `href`

Returns

Type	Description
Elements	elements that have this attribute, empty if none

Remarks

Case insensitive.

GetElementsByAttributeStarting(String)

Find elements that have an attribute name starting with the supplied prefix.

Declaration

public Elements GetElementsByAttributeStarting(string keyPrefix)

Parameters

Type	Name	Description
System.String	keyPrefix	name prefix of the attribute e.g. `data-`

Returns

Type	Description
Elements	elements that have attribute names that start with with the prefix, empty if none.

Remarks

Use data- to find elements that have HTML5 datasets.

GetElementsByAttributeValue(String, String)

Find elements that have an attribute with the specific value.

Declaration

public Elements GetElementsByAttributeValue(string key, string value)

Parameters

Type	Name	Description
System.String	key	name of the attribute
System.String	value	value of the attribute

Returns

Type	Description
Elements	elements that have this attribute with this value, empty if none

Remarks

Case insensitive.

GetElementsByAttributeValueContaining(String, String)

Find elements that have attributes whose value contains the match string.

Declaration

public Elements GetElementsByAttributeValueContaining(string key, string match)

Parameters

Type	Name	Description
System.String	key	name of the attribute
System.String	match	substring of value to search for

Returns

Type	Description
Elements	elements that have attributes containing this text

Remarks

Case insensitive.

GetElementsByAttributeValueEnding(String, String)

Find elements that have attributes that end with the value suffix.

Declaration

public Elements GetElementsByAttributeValueEnding(string key, string valueSuffix)

Parameters

Type	Name	Description
System.String	key	name of the attribute
System.String	valueSuffix	end of the attribute value

Returns

Type	Description
Elements	elements that have attributes that end with the value suffix

Remarks

Case insensitive.

GetElementsByAttributeValueMatching(String, Regex)

Find elements that have attributes whose values match the supplied regular expression.

Declaration

public Elements GetElementsByAttributeValueMatching(string key, Regex pattern)

Parameters

Type	Name	Description
System.String	key	name of the attribute
Regex	pattern	compiled regular expression to match against attribute values

Returns

Type	Description
Elements	elements that have attributes matching this regular expression

GetElementsByAttributeValueMatching(String, String)

Find elements that have attributes whose values match the supplied regular expression.

Declaration

public Elements GetElementsByAttributeValueMatching(string key, string regex)

Parameters

Type	Name	Description
System.String	key	name of the attribute
System.String	regex	regular expression to match against attribute values. You can use embedded flags (such as (?i) and (?m) to control regex options.

Returns

Type	Description
Elements	elements that have attributes matching this regular expression

GetElementsByAttributeValueNot(String, String)

Find elements that either do not have this attribute, or have it with a different value.

Declaration

public Elements GetElementsByAttributeValueNot(string key, string value)

Parameters

Type	Name	Description
System.String	key	name of the attribute
System.String	value	value of the attribute

Returns

Type	Description
Elements	elements that do not have a matching attribute

Remarks

Case insensitive.

GetElementsByAttributeValueStarting(String, String)

Find elements that have attributes that start with the value prefix.

Declaration

public Elements GetElementsByAttributeValueStarting(string key, string valuePrefix)

Parameters

Type	Name	Description
System.String	key	name of the attribute
System.String	valuePrefix	start of attribute value

Returns

Type	Description
Elements	elements that have attributes that start with the value prefix

Remarks

Case insensitive.

GetElementsByClass(String)

Find elements that have this class, including or under this element.

Declaration

public Elements GetElementsByClass(string className)

Parameters

Type	Name	Description
System.String	className	the name of the class to search for.

Returns

Type	Description
Elements	elements with the supplied class name, empty if none

Remarks

Case insensitive.

Elements can have multiple classes (e.g. <div class="header round first"> . This method checks each class, so you can find the above with el.GetElementsByClass("header"); .

GetElementsByIndexEquals(Int32)

Find elements whose sibling index is equal to the supplied index.

Declaration

public Elements GetElementsByIndexEquals(int index)

Parameters

Type	Name	Description
System.Int32	index	0-based index

Returns

Type	Description
Elements	elements equal to index

GetElementsByIndexGreaterThan(Int32)

Find elements whose sibling index is greater than the supplied index.

Declaration

public Elements GetElementsByIndexGreaterThan(int index)

Parameters

Type	Name	Description
System.Int32	index	0-based index

Returns

Type	Description
Elements	elements greater than index

GetElementsByIndexLessThan(Int32)

Find elements whose sibling index is less than the supplied index.

Declaration

public Elements GetElementsByIndexLessThan(int index)

Parameters

Type	Name	Description
System.Int32	index	0-based index

Returns

Type	Description
Elements	elements less than index

GetElementsByTag(String)

Finds elements, including and recursively under this element, with the specified tag name.

Declaration

public Elements GetElementsByTag(string tagName)

Parameters

Type	Name	Description
System.String	tagName	The tag name to search for (case insensitively).

Returns

Type	Description
Elements	a matching unmodifiable list of elements. Will be empty if this element and none of its children match.

GetElementsContainingOwnText(String)

Find elements that directly contain the specified string.

Declaration

public Elements GetElementsContainingOwnText(string searchText)

Parameters

Type	Name	Description
System.String	searchText	to look for in the element's own text

Returns

Type	Description
Elements	elements that contain the string, case insensitive.

Remarks

The search is case insensitive. The text must appear directly in the element, not in any of its descendants.

GetElementsContainingText(String)

Find elements that contain the specified string.

Declaration

public Elements GetElementsContainingText(string searchText)

Parameters

Type	Name	Description
System.String	searchText	to look for in the element's text

Returns

Type	Description
Elements	elements that contain the string, case insensitive.

Remarks

The search is case insensitive. The text may appear directly in the element, or in any of its descendants.

GetElementsMatchingOwnText(Regex)

Find elements whose own text matches the supplied regular expression.

Declaration

public Elements GetElementsMatchingOwnText(Regex pattern)

Parameters

Type	Name	Description
Regex	pattern	regular expression to match text against

Returns

Type	Description
Elements	elements matching the supplied regular expression.

GetElementsMatchingOwnText(String)

Find elements whose text matches the supplied regular expression.

Declaration

public Elements GetElementsMatchingOwnText(string regex)

Parameters

Type	Name	Description
System.String	regex	regular expression to match text against. You can use embedded flags (such as (?i) and (?m) to control regex options.

Returns

Type	Description
Elements	elements matching the supplied regular expression.

GetElementsMatchingText(Regex)

Find elements whose text matches the supplied regular expression.

Declaration

public Elements GetElementsMatchingText(Regex pattern)

Parameters

Type	Name	Description
Regex	pattern	regular expression to match text against

Returns

Type	Description
Elements	elements matching the supplied regular expression.

GetElementsMatchingText(String)

Find elements whose text matches the supplied regular expression.

Declaration

public Elements GetElementsMatchingText(string regex)

Parameters

Type	Name	Description
System.String	regex	regular expression to match text against. You can use embedded flags (such as (?i) and (?m) to control regex options.

Returns

Type	Description
Elements	elements matching the supplied regular expression.

GetHashCode()

Returns the hash code for this instance.

Declaration

public override int GetHashCode()

Returns

Type	Description
System.Int32

Overrides

Node.GetHashCode()

HasClass(String)

Tests if this element has a class.

Declaration

public bool HasClass(string className)

Parameters

Type	Name	Description
System.String	className	name of class to check for

Returns

Type	Description
System.Boolean	true if it does, false if not

Remarks

Case insensitive.

InsertChildren(Int32, IEnumerable<Node>)

Inserts the given child nodes into this element at the specified index.

Declaration

public Element InsertChildren(int index, IEnumerable<Node> children)

Parameters

Type	Name	Description
System.Int32	index	0-based index to insert children at. Specify `0` to insert at the start, `-1` at the end
IEnumerable<Node>	children	child nodes to insert

Returns

Type	Description
Element	this element, for chaining.

Remarks

Current nodes will be shifted to the right. The inserted nodes will be moved from their current parent. To prevent moving, copy the nodes first.

Prepend(String)

Add inner HTML into this element.

Declaration

public Element Prepend(string html)

Parameters

Type	Name	Description
System.String	html	HTML to add inside this element, before the existing HTML

Returns

Type	Description
Element	this element

Remarks

The supplied HTML will be parsed, and each node prepended to the start of the element's children.

PrependChild(Node)

Add a node to the start of this element's children.

Declaration

public Element PrependChild(Node child)

Parameters

Type	Name	Description
Node	child	node to add.

Returns

Type	Description
Element	this element, so that you can add more child nodes or elements.

PrependElement(String)

Create a new element by tag name, and add it as the first child.

Declaration

public Element PrependElement(string tagName)

Parameters

Type	Name	Description
System.String	tagName	the name of the tag (e.g. `div` ).

Returns

Type	Description
Element	the new element, to allow you to add content to it, e.g.: `parent.PrependElement("h1").Attr("id", "header").Text("Welcome");`

PrependText(String)

Create and prepend a new TextNode to this element.

Declaration

public Element PrependText(string text)

Parameters

Type	Name	Description
System.String	text	the unencoded text to add

Returns

Type	Description
Element	this element

RemoveClass(String)

Remove a class name from this element's class attribute.

Declaration

public Element RemoveClass(string className)

Parameters

Type	Name	Description
System.String	className	class name to remove

Returns

Type	Description
Element	this element

Select(String)

Find elements that match the Selector CSS query, with this element as the starting context. Matched elements may include this element, or any of its children.

Declaration

public Elements Select(string cssQuery)

Parameters

Type	Name	Description
System.String	cssQuery	a Selector CSS-like query

Returns

Type	Description
Elements	elements that match the query (empty if none match)

Remarks

This method is generally more powerful to use than the DOM-type GetElementBy* methods, because multiple filters can be combined, e.g.:

el.Select("a[href]") - finds links ( a tags with href attributes)
el.Select("a[href*=example.com]") - finds links pointing to example.com (loosely)

See the query syntax documentation in Selector .

ToggleClass(String)

Toggle a class name on this element's class attribute: if present, remove it; otherwise add it.

Declaration

public Element ToggleClass(string className)

Parameters

Type	Name	Description
System.String	className	class name to toggle

Returns

Type	Description
Element	this element

ToString()

Converts the value of this instance to a string.

Declaration

public override string ToString()

Returns

Type	Description
System.String

Overrides

Node.ToString()

Wrap(String)

Wrap the supplied HTML around this element.

Declaration

public Element Wrap(string html)

Parameters

Type	Name	Description
System.String	html	HTML to wrap around this element, e.g. `<div class="head"></div>` . Can be arbitrarily deep.

Returns

Type	Description
Element	this element, for chaining.

Extension Methods

FluentUtility.TagName(Element, String)

FluentUtility.ClassNames(Element, ICollection<String>)

FluentUtility.Val(Element, String)

FluentUtility.Html(Element, String)

Class Element

Inheritance

Inherited Members

Namespace: Supremes.Nodes

Assembly: Supremes.dll

Syntax

Remarks

Properties

Children

Declaration

Property Value

Remarks

See Also

ClassName

Declaration

Property Value

Remarks

ClassNames

Declaration

Property Value

Remarks

See Also

CssSelector

Declaration

Property Value

Remarks

Data

Declaration

Property Value

Remarks

See Also

DataNodes

Declaration

Property Value

Remarks

See Also

Dataset

Declaration

Property Value

Remarks

ElementSiblingIndex

Declaration

Property Value

Remarks

FirstElementSibling

Declaration

Property Value

HasText

Declaration

Property Value

Html

Declaration

Property Value

Remarks

See Also

Id

Declaration

Property Value

IsBlock

Declaration

Property Value

Remarks

LastElementSibling

Declaration

Property Value

NextElementSibling

Declaration

Property Value

Remarks

See Also

OwnText

Declaration

Property Value

Remarks

See Also

Parent

Declaration

Property Value

Parents

Declaration