goquery

goquery brings jQuery’s familiar chainable syntax to Go, letting you parse, traverse, and manipulate HTML documents in server-side scraping and processing tools. Built on Go’s net/html parser and the cascadia CSS selector library, it exposes a Selection type that mirrors jQuery’s API - Find, Filter, Each, Attr, Text, and dozens more - so anyone who has used jQuery can start extracting data from HTML in Go within minutes.

Because it wraps net/html rather than reimplementing a DOM, goquery stays lightweight and predictable: no browser, no JavaScript execution, just fast structural queries and manipulation over parsed HTML nodes. It has been stable and widely used since 2012, making it the de facto standard for web scraping and HTML processing in the Go ecosystem.

What You Get

• jQuery-style Selection API - Find, Filter, Each, Map, and chainable traversal methods that mirror jQuery’s naming and semantics
• CSS selector matching via cascadia - full CSS selector support for locating nodes, plus a Matcher interface for precompiled, reusable selectors
• Document manipulation methods - Append, Prepend, ReplaceWith, Wrap, and other DOM-editing functions for building or transforming HTML
• Property and attribute helpers - Attr, AttrOr, AddClass, RemoveClass, Html, and Text for reading and writing node data
• Zero external runtime dependencies beyond cascadia and golang.org/x/net - a minimal footprint that’s easy to vendor and audit

Common Use Cases

• Web scraping pipelines - extracting structured data (titles, links, prices, article bodies) from fetched HTML pages
• HTML sanitization and transformation - rewriting or stripping elements before re-serving or storing content
• Test assertions on rendered HTML - verifying that server-rendered templates contain expected elements or attributes
• Static site or feed generators - querying and reshaping HTML fragments during a build pipeline

Under The Hood

Architecture goquery is organized as a flat, single-package library split by behavior category rather than by layer: array.go (positional access like Eq/First/Last), expand.go (Add/Union), filter.go (Filter/Not/Has), iteration.go (Each/Map), manipulation.go (Append/Wrap/Clone), property.go (Attr/Text/Html/classes), query.go (Is/Contains), and traversal.go (Find/Parent/Children/Siblings). All of these operate on the two core types defined in type.go - Document (wraps a root *html.Node) and Selection (holds a slice of *html.Node plus a back-reference to the previous Selection for End()/chaining). Every method returns a new *Selection, giving the library’s chainable, jQuery-like feel while keeping mutation localized to explicit manipulation calls; selector strings are compiled through a Matcher interface (compileMatcher in type.go) so cascadia.Selector or a custom Matcher can be swapped in transparently, and an invalidMatcher fallback means malformed selectors fail closed (matching nothing) instead of panicking.

Tech Stack The module (go.mod) declares Go 1.25+ and exactly two dependencies: github.com/andybalholm/cascadia (CSS selector compilation and matching) and golang.org/x/net (specifically net/html for the actual HTML tokenizer/parser). There is no third dependency beyond the Go standard library - net/http is used only for the deprecated NewDocument/NewDocumentFromResponse convenience constructors. CI (.github/workflows/test.yml) runs the test suite across Go 1.26 and 1.27 on Ubuntu, macOS, and Windows, confirming the library’s portability claims and its policy of testing against the latest two Go releases.

Code Quality The repository pairs almost every source file with a same-named test.go counterpart (19 test files against 11 non-test .go files), plus a dedicated bench*.go suite covering array operations, filtering, expansion, iteration, property access, and traversal for performance regression tracking. example_test.go provides runnable Example/ExampleXxx functions that double as documentation verified by go test. Error handling favors returning errors from parsing entry points (NewDocumentFromReader) rather than panicking, and selector compilation failures are handled via the invalidMatcher pattern rather than propagating a panic through chained calls. Naming is consistent and deliberately mirrors jQuery’s XxxSelection/XxxNodes/XxxMatcher/XxxFunction convention, documented explicitly in doc.go, which keeps the large method surface predictable despite its size.

What Makes It Unique goquery’s distinguishing choice is fidelity to jQuery’s actual method-naming and behavioral conventions rather than inventing a more “Go-idiomatic” API from scratch - the maintainers explicitly reference Go’s own fmt package as precedent for following a well-known API shape instead of designing anew. It layers this on top of, rather than replacing, the standard library’s net/html tokenizer, so it inherits Go’s HTML5-compliant parsing for free while adding only the selection/traversal/manipulation layer jQuery users expect. The addition of a generics-based Map function and an EachIter range-over-func iterator in recent releases shows the library adopting modern Go idioms (generics, iterators) without breaking its decade-plus-stable public API - the maintainers state explicitly that the API is now stable and will not break.