HTML DOM Navigation in Java

Aspose.HTML for Java provides several ways to locate and inspect content in an HTMLDocument. Java code can move between related DOM nodes, traverse a document with a filter, evaluate an XPath expression, or select elements with a CSS selector.

Use direct DOM navigation when the position of a node is already known, TreeWalker with NodeFilter for controlled traversal, XPath for structural expressions, and CSS selectors for familiar matching by tag, class, ID, or attribute.

Navigate the HTML DOM in Java

The Node API provides methods for moving through parent, child, and sibling relationships. Node-based methods can return text, comment, or element nodes, while element-specific methods skip non-element nodes.

Java method	Result
getFirstChild() and getLastChild()	The first or last child node, including non-element nodes
getNextSibling() and getPreviousSibling()	The adjacent sibling node
getChildNodes()	A NodeList containing all child nodes
getFirstElementChild() and getLastElementChild()	The first or last child element
getNextElementSibling() and getPreviousElementSibling()	The adjacent sibling element

The following example creates an HTML document from a string, reads its first child element, and then moves to the next element sibling:

// Navigate the HTML DOM using Java

// Prepare HTML code
String html_code = "<span>Hello,</span> <span>World!</span>";

// Initialize a document from the prepared code
HTMLDocument document = new HTMLDocument(html_code, ".");

// Get the reference to the first child (first <span>) of the document body
Element element = document.getBody().getFirstElementChild();
System.out.println(element.getTextContent());
// @output: Hello,

// Get the reference to the second <span> element
element = element.getNextElementSibling();
System.out.println(element.getTextContent());
// @output: World!

Filter Nodes with TreeWalker and NodeFilter

For controlled traversal, create a TreeWalker or NodeIterator and supply a custom NodeFilter. The following filter accepts <img> elements and skips other nodes:

// Create custom NodeFilter to accept only image elements in Java

public static class OnlyImageFilter extends NodeFilter {
    @Override
    public short acceptNode(Node n) {
        // The current filter skips all elements, except IMG elements
        return "img".equals(n.getLocalName())
                ? FILTER_ACCEPT
                : FILTER_SKIP;
    }
}

Use the filter when creating a TreeWalker, call nextNode() to advance through accepted nodes, and read the current node as an HTMLImageElement:

// Filter HTML elements using TreeWalker and custom NodeFilter in Aspose.HTML for Java

// Prepare HTML code
String code = "    <p> Hello, </p>\n" +
        "    <img src = 'image1.png'>\n" +
        "    <img src = 'image2.png'>\n" +
        "    <p> World! </p>\n";

// Initialize a document based on the prepared code
HTMLDocument document = new HTMLDocument(code, ".");

// To start HTML navigation, we need to create an instance of TreeWalker
// The specified parameters mean that it starts walking from the root of the document, iterating all nodes, and using our custom implementation of the filter
ITreeWalker iterator = document.createTreeWalker(document, NodeFilter.SHOW_ALL, new NodeFilterUsageExample.OnlyImageFilter());
// Use
while (iterator.nextNode() != null) {
    // Since we are using our own filter, the current node will always be an instance of the HTMLImageElement
    // So, we don't need the additional validations here
    HTMLImageElement image = (HTMLImageElement) iterator.getCurrentNode();

    System.out.println(image.getSrc());
    // @output: image1.png
    // @output: image2.png
}

Select HTML Elements with XPath

XPath selects nodes through expressions based on document structure, attributes, and relationships. It is useful when a query must describe more than a simple tag, class, or ID match.

The following example calls document.evaluate() with the expression //*[@class='happy']//span and iterates through the matching <span> nodes:

1. Create an HTML document containing the elements to inspect.
2. Evaluate an XPath expression against the document.
3. Request an iterable XPath result.
4. Call iterateNext() until every matching node has been processed.

// Select HTML elements using XPath expression in Aspose.HTML for Java

// Prepare HTML code
String code = "<div class='happy'>\n" +
        "        <div>\n" +
        "            <span> Hello! </span>\n" +
        "        </div>\n" +
        "    </div>\n" +
        "    <p class='happy'>\n" +
        "        <span> World! </span>\n" +
        "    </p>\n";

// Initialize a document based on the prepared code
HTMLDocument document = new HTMLDocument(code, ".");

// Here, we evaluate the XPath expression where we select all child <span> elements from elements whose 'class' attribute equals to 'happy'
IXPathResult result = document.evaluate("//*[@class='happy']//span",
        document,
        null,
        XPathResultType.Any,
        null
);

// Iterate over the resulted nodes
for (Node node; (node = result.iterateNext()) != null; ) {
    System.out.println(node.getTextContent());
    // @output: Hello!
    // @output: World!
}

Select HTML Elements with CSS Selectors

CSS selectors provide concise matching by element name, class, ID, attribute, and relationship. The example uses document.querySelectorAll(".happy span") to select descendant <span> elements inside elements whose class includes happy.

1. Create an HTML document containing the target elements.
2. Pass a CSS selector to querySelectorAll().
3. Iterate through the returned NodeList and read the selected elements.

// Select HTML elements using CSS selector querySelectorAll method in Aspose.HTML for Java

// Prepare HTML code
String code = "<div class='happy'>\n" +
        "        <div>\n" +
        "            <span> Hello, </span>\n" +
        "        </div>\n" +
        "    </div>\n" +
        "    <p class='happy'>\n" +
        "        <span> World! </span>\n" +
        "    </p>\n";

// Initialize a document based on the prepared code
HTMLDocument document = new HTMLDocument(code, ".");

// Here, we create a CSS Selector that extracts all elements whose 'class' attribute equals to 'happy' and their child SPAN elements
NodeList elements = document.querySelectorAll(".happy span");

// Iterate over the resulted list of elements
elements.forEach(element -> {
    System.out.println(((HTMLElement) element).getInnerHTML());
    // @output: Hello,
    // @output: World!
});

Choose an HTML Selection Method

Method	Best suited for
Direct DOM navigation	Moving between known parents, children, or siblings
TreeWalker and NodeFilter	Traversing a document while accepting or skipping specific nodes
XPath	Selecting nodes with structural paths and relationship conditions
CSS selectors	Matching elements with familiar web selector syntax

Common HTML Navigation Issues

Issue	Cause	Fix
getFirstChild() returns a text node	Whitespace between tags is represented by a DOM text node.	Use getFirstElementChild() when only an element is required.
XPath or CSS query returns no nodes	The expression does not match the DOM loaded by the application.	Inspect the actual elements and attributes, then test a simpler expression first.
A cast to an element type fails	The traversal can return nodes of another type.	Restrict accepted nodes with NodeFilter or check the node type before casting.

Related Aspose.HTML Articles

• Use CSS Selectors in Java – apply querySelector() and querySelectorAll() to practical extraction and DOM-update tasks.
• Use XPath in HTML with Java – evaluate XPath expressions and extract values from selected nodes.
• Data Extraction in Java – choose other HTML and web data extraction workflows.
• Extract Images from Website – locate image elements and download their resources.
• Extract SVG from Website – extract inline SVG markup and external SVG files.

Try AI Keyword Extractor

Aspose.HTML offers AI Keyword Extractor, an online tool for extracting keywords from a web page, plain text, or a file without writing Java code.