Repository navigation
Releases
Releases · jsdom/jsdom
v31.0.1
- Improved performance of computed style reads, selector matching, CSS variable substitution, CSS shorthand updates, and focus handling on pages with many style rules. (@scttcper)
- Improved performance when building detached DOM trees and reading
node.isConnected. (@scttcper) - Fixed
element.tabIndexhandling of invalid and out-of-rangetabindex=""values to use the element's default instead of returning zero or wrapping. Values with trailing non-digits now use their leading integer, sotabindex="1e2"yields1instead of100. (@rome-xi) - Fixed CSS
ident()results containing spaces or leading digits losing their required escaping during serialization and variable substitution. (@scttcper) - Fixed 'max-lines' values combining an integer and
autoto serialize with the integer first, such as3 auto.
v31.0.0
Breaking changes
- Changed the optional canvas and image decoding backend from
canvasto@napi-rs/canvas. Install@napi-rs/canvasv1.0.13 or later in the v1.x series alongside jsdom; installingcanvasalone no longer enables this support. The new backend provides prebuilt Skia binaries on supported platforms, and rendering and encoded image bytes can differ. Projects using native canvas objects or custom font registration should follow the canvas migration guidance. Added WebP serialization throughcanvas.toDataURL()andcanvas.toBlob(). Fixed image loading to wait for decoding before firingload, discard obsolete source requests, avoid refetching when dimensions change, and prevent failed images from drawing stale contents. Fixed canvas context and serialization behavior, including unsupported context types, read-onlyctx.canvas, image-drawing exceptions, MIME type and quality normalization, and asynchronousnullresults fromcanvas.toBlob()for empty canvases or encoding failures. (@Brooooooklyn) - Changed CSS parsing, selector matching, and computed styles to use a new integrated implementation, with substantially expanded support and faster selector queries and repeated style reads. This includes cascade layers, nesting,
@scope, custom-property substitution and registration through@propertyandCSS.registerProperty(), typedattr(), conditionalif(), shadow-tree styling with:host,::slotted(), and::part(), pseudo-element computed styles, and constructable stylesheets withdocument.adoptedStyleSheetsandshadowRoot.adoptedStyleSheets. Fixed numerous cascade, shorthand, serialization, and default-style issues; computed declarations now stay live across DOM and stylesheet changes. CSS serialization and computed values can differ from previous releases. - Changed HTML and XML parsing to pause at blocking scripts until their required resources are ready. The
JSDOMconstructor,JSDOM.fromURL(), andJSDOM.fromFile()can now return partially parsed documents. Wait forDOMContentLoadedfor the finished tree, or the window'sloadevent for load-delaying resources, checkingdocument.readyStatefirst in case the event has already fired. XML syntax errors encountered after asynchronous parsing resumes are reported through the virtual console as"xml-parsing"errors.
Other changes
- Added
window.reportError(), which dispatches anerrorevent and reports uncanceled errors to the virtual console. (@sarankumar1325) - Added
element.ariaBrailleLabelandelement.ariaBrailleRoleDescription. (@Kjubikstronk) - Fixed page-completion
loadevents to fire only on the window. Usewindow.addEventListener("load", ...)orwindow.onloadinstead of listening on the document. - Fixed
document.open(), including implicit calls fromdocument.write(), to clear event listeners and handlers from the document, its descendants, and its window when replacing the input stream. - Fixed
document.write()to process successive writes through the parser's input stream, preserve insertion points across nested scripts, and make completed text immediately visible. Script-created input streams now remain open untildocument.close(). - Fixed dynamically inserted scripts to respect
script.async = falseexecution order, use their source text and document from preparation time, and avoid executing after adoption into another document. Scripts parsed through inert fragment APIs no longer execute when subsequently inserted. - Fixed unrelated images, stylesheets, and frames being delayed behind scripts, and resource completion events firing before nested stylesheet imports finish. Cyclic imports no longer prevent completion, and
<style>elements in shadow trees now fireloadevents. - Fixed
window.stop()to cancel pending subresource andXMLHttpRequestrequests in descendant frames and suppress completion events for canceled loads, while allowing subsequent requests to proceed. - Fixed repeated
document.close()calls replaying readiness and load events, and incorrect iframe load events when reopening documents from event handlers. - Fixed memory leaks where pending request interceptor promises retained closed windows, introduced in v28.0.0.
- Fixed focus remaining on elements that become non-focusable after DOM or style changes. Focus now moves asynchronously to the document's viewport, and
element.blur()can release it immediately. - Fixed
document.hasFocus()returning false before an element is focused or during focus transitions within the document, including inside frames. - Fixed
<template>parsing andtemplate.innerHTMLserialization in XML documents, including templates with namespace prefixes. (@b84330808) - Fixed
rect.toJSON()andperformance.toJSON()to create their result objects in the method's realm instead of the host Node.js realm.
v30.1.3
- Improved performance of
getComputedStyle()and computed CSS property reads, including with stylesheets containing attribute selectors. (@scttcper, @asamuzaK) - Fixed slowdowns when focusing elements and running interaction tests, which regressed in v30.1.2. (@scttcper)
- Fixed
XMLHttpRequestreusing credentials supplied toxhr.open()after cross-origin redirects, including in response to authentication challenges from the destination. - Fixed
XMLHttpRequestincorrectly sending and accepting cookies after cross-origin redirects back to the document's origin whenxhr.withCredentialsis false. - Fixed exceptions from malformed CSS math functions, such as
calc(0px - @submenu_space), while parsing documents, stylesheets, and style declarations. (@rnavarro) - Fixed
getComputedStyle()ignoring style rules nested inside multiple@mediarules. - Fixed CSS shorthands overwriting longhands with higher priority or specificity during style computation, including declarations containing CSS variables.
- Fixed
getComputedStyle()returning unresolved or inconsistent shorthand values, including for 'background', 'border', 'flex', 'font', 'margin', and 'padding', and incorrect shorthand defaults and inheritance. - Fixed computed background positions to resolve font-relative lengths using the final font size and handle multiple image layers correctly.
- Fixed computed 'color' values depending on property read order, including unresolved
color-mix()results, which regressed in v29.0.2. - Fixed
currentcolorborder colors incorrectly becoming transparent when 'color' useslight-dark()or relative color syntax. - Fixed CSS calculations that reduce to a percentage incorrectly producing pixel values, which regressed in v30.0.0.
- Fixed numeric font weights in the 'font' shorthand incorrectly setting 'line-height'.
- Fixed selector matching involving XML namespaces, and selectors such as
[data-a|=""]failing to match empty values and values beginning with-. (@asamuzaK)
v30.1.2
- Updated URLs to support Unicode v18.0.0 in internationalized domain names.
- Reduced package size and memory use for CSS property definitions. (@scttcper)
- Fixed severe slowdowns when building large DOM trees, including SVG charts with D3, which regressed in v30.1.0. (@cmdcolin)
- Fixed exponentially slow reads of empty inherited CSS custom properties in deeply nested documents, and custom properties incorrectly inheriting past an
initialreset. (@scttcper) - Fixed
getComputedStyle()returning stale results after editing stylesheet declarations, selectors, or media queries, including in imported stylesheets. - Fixed selector matching and computed styles after changes to form control checkedness, indeterminacy, selection, values, and validity, including during form resets and canceled clicks.
- Fixed computed styles for
:focus,:focus-visible,:focus-within, and selectors containing them after focus changes, including inside focus and blur listeners. (@asamuzaK) - Fixed
element.focus()incorrectly focusing elements hidden by 'display', including through shadow hosts and slots, and elements excluded by shadow DOM slot assignment. (@asamuzaK) - Fixed
getComputedStyle()throwing for elements without inline-style support, including XML and MathML elements. - Fixed a memory leak where stylesheet parsing retained the last parsed stylesheet's window after
window.close(). - Fixed memory growth from long-lived
MutationObserverinstances retaining bookkeeping for garbage-collected nodes. (@scttcper) - Fixed retained
select.selectedOptionscollections becoming stale after selection changes and form resets. - Fixed rejection of negative CSS sizing values, including for 'min-width', 'min-height', 'max-width', and 'max-height', which regressed in v30.1.0.
- Fixed handling of deeply nested
color-mix()expressions, including exceptions during color resolution. (@asamuzaK)
v30.1.1
- Fixed spurious window
blurandfocusoutevents and incorrectevent.relatedTargetvalues when focusing an element after removing the previously focused element, which regressed in v30.1.0. (@asamuzaK) - Fixed focus and blur behavior across frames, and focusing the document's viewport through
document.documentElement.focus(). (@asamuzaK) - Fixed focus targets removed or disabled by
blurlisteners becoming active, and text selections made by focus and blur listeners being overwritten. (@asamuzaK) - Fixed
element.focus()incorrectly focusing disabled form controls and<input type="hidden">elements withtabindex="". (@scttcper) - Fixed invalid
style.setProperty()calls changing existing!importantpriorities, serialized styles, or mutation records. (@FedgeNo) - Fixed
!importanthandling when updating CSS longhands after shorthands, using variables or CSS-wide keywords, and assigning style properties directly. (@FedgeNo) - Fixed
<noscript>parsing withincludeNodeLocations: trueor inside frames to honor therunScriptsoption. - Fixed the
storageQuotaoption being ignored by frames. - Fixed encoding detection of HTML and XML byte input to honor XML encoding declarations and detect UTF-16 without a byte order mark.
- Fixed exceptions caused by truncated
charsetparameters in<meta>elements, and encoding detection incorrectly using incomplete<meta>tags. (@FedgeNo) - Fixed XML serialization errors for namespaces named
constructor,toString,__proto__, or"null", and incorrect reuse of namespace prefixes declared on sibling elements. - Fixed
element.innerHTMLandelement.outerHTMLin XML documents to reject invalid characters in attribute values and avoid stack overflows on large strings. - Fixed selector matching for
:lang(),:nth-child(... of ...)after mutations, and:has()with duplicate IDs or nested logical pseudo-classes. (@asamuzaK)
v30.1.0
jsdom is feeling the AGI!
This release is dedicated to @scttcper, who unleashed @codex upon jsdom and found tons of performance improvements. Along the way, he found and fixed many correctness issues as well.
We really appreciate his thoughtful PRs, which did a great job following the project's contribution guidelines, and were clearly human-curated, with their PR descriptions edited to be brief and respectful of the maintainers' time.
Thanks to @scttcper, as well as all the other contributors of this release (most of whom were AI-assisted).
- Added named access to elements on
document, such asdocument.myFormfor<form name="myForm">. (@vojtisprime11) - Added
QuotaExceededError, including its use for storage quota errors and oversizedcrypto.getRandomValues()requests. - Added support for the relaxed DOM naming rules when creating elements, attributes, and document types.
- Improved performance of DOM construction, tree mutations, range operations, and live collection access, especially on large documents. (@scttcper, @erezrokah)
- Improved performance of
getComputedStyle(), style changes, and CSS serialization. (@scttcper, @jhult) - Improved performance of event dispatch, form control and label lookups, and updates to
<select>elements and radio button groups. (@scttcper) - Reduced memory use when creating and working with DOM nodes, attributes, event listeners, and mutation observers. (@scttcper)
- Changed
window.close()to preserve access to the document and its DOM through retained references. - Fixed
element.querySelectorAll()returning no matches when the first part of the selector matches the element itself, which regressed in v30.0.0. (@asamuzaK) - Fixed case sensitivity in CSS attribute selectors, including selectors matching
data-state="",title="", and other case-sensitive values. (@asamuzaK) - Fixed
document.querySelector()failing to find a matching element when an earlier element has the same ID but does not match the rest of the selector. (@vojtisprime11) - Fixed
:focusmatching in shadow trees. (@asamuzaK) - Fixed DOM insertion and replacement, including valid
document.replaceChildren()calls, invalid document element and doctype placements, and mutations duringelement.replaceWith(). - Fixed the ordering of script execution, custom element callbacks, iframe loading, and mutation observer notifications during DOM insertion, including in shadow trees.
- Fixed queued events and navigation continuing after
window.close()or iframe removal, and prevented new scripts, resource loads, timers, and animation frames from starting in destroyed documents. (@scttcper) - Fixed parent documents waiting indefinitely for loading to finish when a child iframe removes itself during loading.
- Fixed request cancellation across redirects, during pending
requestInterceptor()callbacks, and when reusing anXMLHttpRequestafter aborting it. - Fixed resource loading and
JSDOM.fromURL()potentially hanging when response handling throws and response stream cleanup does not finish. - Fixed successful cached resource loads being treated as aborted.
- Fixed
getComputedStyle()anddocument.styleSheetsusing the wrong stylesheet order after inserting or updating<style>elements. - Fixed
getComputedStyle()ignoring nested@importand@mediarules in imported stylesheets, and returning stale results after imports finish loading. - Fixed style invalidation, stylesheet removal, and frame source updates in shadow trees.
- Fixed repeated
getComputedStyle()calls changing case-sensitive background URLs, and inconsistent resolution of border shorthands containing system colors. (@scttcper) - Fixed computed border widths, including borderless elements incorrectly reporting
16px, which regressed in v30.0.0. (@Alberto-BaseNet) - Fixed
getComputedStyle()to resolve'font-weight'keywords to numeric values. (@tianrking) - Fixed
getComputedStyle()to convert lengths to pixels inside CSS math functions containing percentages, and to resolve percentages in'font-size'math functions. (@soroushm) - Fixed serialization of
min()andmax()containing nestedcalc(), which regressed in v30.0.0. (@asamuzaK) - Fixed CSS values mixing lengths or percentages with math functions, such as
'grid-template-columns'values containing both100pxandcalc(). (@rome-xi) - Fixed parsing of
'background'and'border'shorthands with adjacent components, such asurl(a.png)no-repeat, including a crash when parsing inline styles. Also fixed handling of invalid shorthand assignments and escaped or unusual characters in CSS declarations. (@asamuzaK) - Fixed parsing of unitless zero values in
'flex'shorthands, such as35 1 0, and rejection of negative'flex-basis'lengths and percentages. (@asamuzaK) - Fixed shorthand style assignments producing extra mutation records and custom element callbacks for intermediate values. (@scttcper)
- Fixed
RangeandSelectionhandling of CDATA sections, including boundary offsets and range cloning, extraction, deletion, insertion, and stringification. (@scttcper) - Fixed
text.normalize()incorrectly removing the text node or merging its siblings. (@scttcper) - Fixed cloning and importing CDATA sections and processing instructions whose contents have been modified, and serialization of CDATA sections adopted into HTML documents.
- Fixed stale named-property collections on
window, and incorrect named access from empty or namespacedid=""andname=""values. (@scttcper) - Fixed elements in documents created with
DOMParserordocument.implementation.createHTMLDocument()appearing as named properties onwindowand being retained in memory. (@Iaotle) - Fixed memory leaks from mutation observers retaining observed nodes, abort signals retaining removed event listeners, and storage event tracking retaining closed windows. (@scttcper)
- Fixed
storageevents being sent to windows created after the storage change, and ensured surviving recipients still receive events when the source document is destroyed. - Fixed attribute lookups after namespace prefix changes, and namespaced attributes incorrectly affecting ID lookups and element behavior. (@scttcper)
- Fixed
input.listin detached element trees. (@scttcper) - Fixed
attr.ownerDocumentafter setting an attribute node on an element in another document or adopting its element. (@Kjubikstronk) - Fixed fresh
element.getElementsByTagName()calls using the previous document's case-sensitivity rules after adoption between HTML and XML documents. (@Kjubikstronk) - Fixed
element.tagNamereturning stale casing after adoption between HTML and XML documents. - Fixed radio button grouping and checkedness updates for controls with different form owners, controls outside their form, unnamed controls, and canceled clicks.
- Fixed
<select>selection updates when moving options, and unintended selection resets when moving a whole<select>or changing unrelated descendants. - Fixed cloning
<input>elements to preserveinput.indeterminate. - Fixed focus state after removing a focused element or its ancestor, including inside shadow trees.
- Fixed script execution when inserting children into a connected, empty
<script>. (@Kjubikstronk) - Fixed incorrect script execution after changes to
src="", and handling oftype="",for="", andevent="". - Fixed
document.currentScriptduring nested script execution and scripts in shadow trees. - Fixed event dispatch,
window.event, and default passive listener handling for non-node event targets, and event dispatch when user code modifieswindow.constructor. - Fixed
volumechangeandratechangeevents to fire asynchronously. (@christianaurichzm) - Fixed DOM APIs accepting user-created proxies around DOM objects where genuine DOM objects are required.
- Fixed XPath iterator invalidation after DOM mutations and errors for invalid result types.
- Fixed
NodeIteratortraversal when its filter removes nodes. - Fixed
fileReader.readAsText()to honor the blob's MIME type charset when no supported explicit encoding is supplied. - Fixed fractional seconds in time input parsing and serialization. (@Jaybhade)
- Fixed large
input.valueAsNumberassignments for time and local date/time inputs. - Fixed hard wrapping of
<textarea>values to use the numerictextarea.colsvalue. - Fixed
document.readyStateto be"complete"for documents created withdocument.implementation.createDocument()anddocument.implementation.createHTMLDocument(). - Fixed
element.translatefor emptytranslate=""values and elements without a parent. - Fixed XML parsing of lone surrogates to replace them with the Unicode replacement character.
- Fixed
node.lookupNamespaceURI()for thexmlandxmlnsprefixes. (@vojtisprime11) - Fixed
<base>elements to ignoredata:andjavascript:URLs. (@vojtisprime11) - Fixed
svgElement.viewportElementinside<symbol>elements. - Fixed the default
blobEvent.timecodeto beNaN. - Fixed the object shape and property descriptors of
CSS.
v30.0.1
v30.0.0
Breaking changes:
- Node.js minimum version raised to
^22.22.2 || ^24.15.0 || >=26.0.0.
Other changes:
- Added
CSS.escape()andCSS.supports()functions. (@asamuzaK) - Added
'background-position-x'and'background-position-y'CSS properties. (@olagokemills) - Fixed
getComputedStyle()to convert length values into pixels. (@asamuzaK) - Fixed CSS function serialization, e.g., in the return value of
getPropertyValue(). (@asamuzaK) - Fixed the type of error thrown by
document.evaluate()(@dokson)