\r\n\r\n## Interactive Demos\r\n\r\nTry the XSLT and XPath processors directly in your browser:\r\n\r\n**[๐ Visit Interactive Demos](https://designliquido.github.io/xslt-processor/)**\r\n\r\n## How to\r\n\r\nInstall xslt-processor using [npm](https://docs.npmjs.com/about-npm), [ohpm](https://ohpm.openharmony.cn/#/en/home) or [yarn](https://yarnpkg.com):\r\n\r\n```sh\r\nnpm install xslt-processor\r\n```\r\n\r\n```sh\r\nohpm install xslt-processor\r\n```\r\n\r\n```sh\r\nyarn add xslt-processor\r\n```\r\n\r\nWithin your ES2015+ code, import the `Xslt` class, the `XmlParser` class and use it this way:\r\n\r\n```js\r\nimport { Xslt, XmlParser } from 'xslt-processor'\r\n\r\n// xmlString: string of xml file contents\r\n// xsltString: string of xslt file contents\r\n// outXmlString: output xml string.\r\nconst xslt = new Xslt();\r\nconst xmlParser = new XmlParser();\r\n// Either\r\nconst outXmlString = await xslt.xsltProcess(\r\n\txmlParser.xmlParse(xmlString),\r\n\txmlParser.xmlParse(xsltString)\r\n);\r\n// Or\r\nxslt.xsltProcess(\r\n\txmlParser.xmlParse(xmlString),\r\n\txmlParser.xmlParse(xsltString)\r\n).then(output => {\r\n // `output` is equivalent to `outXmlString` (a string with XML).\r\n});\r\n```\r\n\r\nIf you write pre-2015 JS code, make adjustments as needed.\r\n\r\n### Working with browser DOM and XDocument output\r\n\r\nFeature available in v5 (next major) of this library. \r\n\r\nIf you already have a browser DOM `Document` or `Node`, convert it to an `XDocument` without re-parsing XML strings:\r\n\r\n```js\r\nimport { domDocumentToXDocument } from 'xslt-processor'\r\n\r\nconst parser = new DOMParser();\r\nconst nativeDoc = parser.parseFromString('hello', 'text/xml');\r\nconst xDoc = domDocumentToXDocument(nativeDoc);\r\n```\r\n\r\nYou can also run XSLT and get the output as an `XDocument` tree instead of a serialized string:\r\n\r\n```js\r\nimport { Xslt, XmlParser } from 'xslt-processor'\r\n\r\nconst xmlParser = new XmlParser();\r\nconst xslt = new Xslt();\r\n\r\nconst xmlDoc = xmlParser.xmlParse('hello');\r\nconst styleDoc = xmlParser.xmlParse(\r\n '' +\r\n ' ' +\r\n ' ' +\r\n ' ' +\r\n ''\r\n);\r\n\r\nconst outDoc = await xslt.xsltProcessToDocument(xmlDoc, styleDoc);\r\n// outDoc is an XDocument you can traverse or serialize with xmlTransformedText.\r\n```\r\n\r\n### `Xslt` class options\r\n\r\nYou can pass an `options` object to `Xslt` class:\r\n\r\n```js\r\nconst options = {\r\n escape: false,\r\n selfClosingTags: true,\r\n parameters: [{ name: 'myparam', value: '123' }],\r\n outputMethod: 'xml'\r\n};\r\nconst xslt = new Xslt(options);\r\n```\r\n\r\n- `cData` (`boolean`, default `true`): resolves CDATA elements in the output. Content under CDATA is resolved as text. This overrides `escape` for CDATA content.\r\n- `escape` (`boolean`, default `true`): replaces symbols like `<`, `>`, `&` and `\"` by the corresponding [HTML/XML entities](https://www.tutorialspoint.com/xml/xml_character_entities.htm). Can be overridden by `disable-output-escaping`, that also does the opposite, unescaping `>` and `<` by `<` and `>`, respectively.\r\n- `selfClosingTags` (`boolean`, default `true`): Self-closes tags that don't have inner elements, if `true`. For instance, `` becomes ``.\r\n- `outputMethod` (`string`, default `xml`): Specifies the default output method. If `` is declared in your XSLT file, this will be overridden. Valid values: `xml`, `html`, `text`, `xhtml`, `json`, `adaptive`.\r\n- `parameters` (`array`, default `[]`): external parameters that you want to use.\r\n - `name`: the parameter name;\r\n - `namespaceUri` (optional): the namespace;\r\n - `value`: the value. The type is preserved automatically:\r\n - **string** values become `StringValue`;\r\n - **number** values become `NumberValue` (usable in XPath arithmetic);\r\n - **boolean** values become `BooleanValue` (usable in `xsl:if`/`xsl:when` tests);\r\n - Note: in XPath/XSLT, any non-empty string is truthy, so the string \"false\" still behaves as true in tests;\r\n - **`NodeSetValue`** instances are kept as-is (useful for passing additional documents);\r\n - DOM nodes (objects with `nodeType`) are wrapped in a `NodeSetValue`;\r\n - arrays of nodes are wrapped in a `NodeSetValue`.\r\n\r\n**`parameters` examples:**\r\n\r\n```js\r\nimport { Xslt, XmlParser } from 'xslt-processor'\r\n\r\n// String parameter (default behavior)\r\nconst xslt = new Xslt({ parameters: [\r\n { name: 'title', value: 'Hello' }\r\n] });\r\n\r\n// Number parameter โ works in XPath arithmetic ($count + 1 = 43)\r\nconst xslt = new Xslt({ parameters: [\r\n { name: 'count', value: 42 }\r\n] });\r\n\r\n// Boolean parameter โ works in xsl:if / xsl:when tests\r\nconst xslt = new Xslt({ parameters: [\r\n { name: 'debug', value: true }\r\n] });\r\n\r\n// Node-set parameter โ pass an additional document for cross-document lookups\r\nimport { NodeSetValue } from 'xslt-processor/xpath/values'\r\n\r\nconst xmlParser = new XmlParser();\r\nconst lookupDoc = xmlParser.xmlParse('Alpha');\r\n\r\nconst xslt = new Xslt({ parameters: [\r\n { name: 'lookup', value: new NodeSetValue([lookupDoc]) }\r\n] });\r\n// In XSLT: \r\n```\r\n\r\n- `fetchFunction` (`(uri: string) => Promise`, optional): a custom function for loading external resources referenced by `` and ``. Receives the URI and must return the fetched content as a string. Defaults to the global `fetch` API. This is useful for:\r\n - Denying external loading entirely;\r\n - Loading from the local filesystem or other non-HTTP sources;\r\n - Transforming or remapping URIs before fetching.\r\n\r\n**`fetchFunction` examples:**\r\n\r\n```js\r\nimport { readFileSync } from 'fs';\r\n\r\n// Deny all external loading\r\nconst xslt = new Xslt({\r\n fetchFunction: async (uri) => {\r\n throw new Error(`External loading is not allowed: ${uri}`);\r\n }\r\n});\r\n\r\n// Load from local filesystem\r\nconst xslt = new Xslt({\r\n fetchFunction: async (uri) => {\r\n return readFileSync(uri, 'utf-8');\r\n }\r\n});\r\n\r\n// Remap URIs before fetching\r\nconst xslt = new Xslt({\r\n fetchFunction: async (uri) => {\r\n const remapped = uri.replace('https://example.com/', '/local/stylesheets/');\r\n const response = await fetch(remapped);\r\n return response.text();\r\n }\r\n});\r\n```\r\n\r\n- `documentLoader` (`(uri: string) => XNode | null`, optional): resolves URIs passed to the XPath `document()` function ([XSLT 1.0 ยง12.1](https://www.w3.org/TR/1999/REC-xslt-19991116#document)). Receives the URI and must return a parsed `XNode` document, or `null`/`undefined` if it can't be loaded (in which case `document()` returns an empty node-set). Not set by default โ without it, `document()` only resolves the empty-string URI (`document('')`, the stylesheet itself); any other URI returns an empty node-set.\r\n - **Must be synchronous** โ `document()` is evaluated synchronously during XPath evaluation, so it can't `await` a fetch. Pre-load and cache documents ahead of time if they come from an async source.\r\n - Inherited automatically by nested contexts (e.g. inside `xsl:for-each`, `xsl:apply-templates`), so it only needs to be set once on the `Xslt` constructor.\r\n\r\n**`documentLoader` examples:**\r\n\r\n```js\r\nimport { Xslt, XmlParser } from 'xslt-processor';\r\n\r\nconst xmlParser = new XmlParser();\r\n\r\n// Load from an in-memory map (documents already parsed ahead of time)\r\nconst documents = new Map([\r\n ['catalog.xml', xmlParser.xmlParse('Widget')]\r\n]);\r\n\r\nconst xslt = new Xslt({\r\n documentLoader: (uri) => documents.get(uri) ?? null\r\n});\r\n// In XSLT: \r\n\r\n// Load from the local filesystem\r\nimport { readFileSync } from 'fs';\r\n\r\nconst xslt = new Xslt({\r\n documentLoader: (uri) => xmlParser.xmlParse(readFileSync(uri, 'utf-8'))\r\n});\r\n\r\n// Pre-fetch over HTTP, then serve synchronously from cache\r\nconst response = await fetch('https://example.com/catalog.xml');\r\nconst cached = xmlParser.xmlParse(await response.text());\r\n\r\nconst xslt = new Xslt({\r\n documentLoader: (uri) => (uri === 'https://example.com/catalog.xml' ? cached : null)\r\n});\r\n```\r\n\r\n#### JSON Output Format\r\n\r\nWhen using `outputMethod: 'json'`, the XSLT processor will convert the resulting XML document to JSON format. This is useful for APIs and modern JavaScript applications.\r\n\r\n**Example:**\r\n\r\n```js\r\nconst xslt = new Xslt({ outputMethod: 'json' });\r\nconst xmlParser = new XmlParser();\r\n\r\nconst xmlString = `\r\n \r\n Alice\r\n Bob\r\n \r\n`;\r\n\r\nconst xsltString = `\r\n \r\n \r\n \r\n \r\n `;\r\n\r\nconst result = await xslt.xsltProcess(\r\n xmlParser.xmlParse(xmlString),\r\n xmlParser.xmlParse(xsltString)\r\n);\r\n\r\n// result will be a JSON string:\r\n// {\"root\":{\"users\":{\"user\":[\"Alice\",\"Bob\"]}}}\r\n\r\nconst parsed = JSON.parse(result);\r\nconsole.log(parsed.root.users.user); // [\"Alice\", \"Bob\"]\r\n```\r\n\r\n**JSON Structure Rules:**\r\n\r\n- Each element becomes a property in a JSON object\r\n- Text-only elements become string values\r\n- Elements with multiple children of the same name become arrays\r\n- Empty elements are omitted from the output\r\n- Attributes are prefixed with `@` (when present in the output)\r\n- Mixed text and element content uses the `#text` property for text nodes\r\n\r\n#### Adaptive Output Format\r\n\r\nWhen using `outputMethod: 'adaptive'`, the XSLT processor automatically detects the most appropriate output format based on the transformation result. This implements XSLT 3.1 adaptive output behavior.\r\n\r\n**Detection Rules:**\r\n\r\n- If the output contains only text nodes (no elements), it returns as plain text\r\n- If the output contains one or more elements, it returns as XML\r\n\r\n**Example:**\r\n\r\n```js\r\nconst xslt = new Xslt({ outputMethod: 'adaptive' });\r\nconst xmlParser = new XmlParser();\r\n\r\n// Example 1: Pure text output\r\nconst xmlString1 = `Hello World`;\r\nconst xsltString1 = `\r\n \r\n \r\n \r\n \r\n `;\r\n\r\nconst result1 = await xslt.xsltProcess(\r\n xmlParser.xmlParse(xmlString1),\r\n xmlParser.xmlParse(xsltString1)\r\n);\r\nconsole.log(result1); // \"Hello World\" (plain text)\r\n\r\n// Example 2: XML output\r\nconst xmlString2 = `John`;\r\nconst xsltString2 = `\r\n \r\n \r\n \r\n \r\n `;\r\n\r\nconst result2 = await xslt.xsltProcess(\r\n xmlParser.xmlParse(xmlString2),\r\n xmlParser.xmlParse(xsltString2)\r\n);\r\nconsole.log(result2); // \"John\" (XML)\r\n```\r\n\r\n### Direct use in browsers\r\n\r\nYou can simply add a tag like this:\r\n\r\n```html\r\n\r\n```\r\n\r\nAll the exports will live under `globalThis.XsltProcessor` and `window.XsltProcessor`. [See a usage example here](https://github.com/DesignLiquido/xslt-processor/blob/main/interactive-tests/xslt.html).\r\n\r\n## XPath Parser\r\n\r\nTo access the XPath parser, you can use the instance present at `Xslt` class:\r\n\r\n```js\r\nconst xslt = new Xslt();\r\nconst xPath = xslt.xPath;\r\n```\r\n\r\nOr you can import it like this:\r\n\r\n```js\r\nimport { XPath } from 'xslt-processor'\r\n\r\nconst xPath = new XPath();\r\n```\r\n\r\n`XPath` class is an external dependency, [living in its own repository](https://github.com/DesignLiquido/xpath).\r\n\r\n## Introduction\r\n\r\nXSLT-processor contains an implementation of XSLT in JavaScript. Because XSLT uses XPath, it also contains an implementation of XPath that can be used independently of XSLT. This implementation has the advantage that it makes XSLT uniformly available whenever the browser's native `XSLTProcessor()`\r\nis not available such as in Node.js or in web workers.\r\n\r\nXSLT-processor builds on Google's [AJAXSLT](https://github.com/4031651/ajaxslt) which was written before `XSLTProcessor()` became available in browsers, but the code base has been updated to comply with ES2015+ and to make it work outside of browsers.\r\n\r\nThis implementation of XSLT operates at the DOM level on its input documents. It internally uses a DOM implementation to create the output document, but usually returns the output document as text stream. The DOM to construct the output document can be supplied by the application, or else an internal minimal DOM implementation is used. This DOM comes with a minimal XML parser that can be used to generate a suitable DOM representation of the input documents if they are present as text.\r\n\r\n## Building from source\r\n\r\nThe XPath engine lives in a Git submodule at `src/xpath/lib`. A regular `git clone` does **not** fetch it automatically, so the build will fail unless the submodule is initialised.\r\n\r\n### Fresh clone\r\n\r\n```sh\r\ngit clone --recurse-submodules https://github.com/DesignLiquido/xslt-processor.git\r\ncd xslt-processor\r\nyarn install\r\nyarn build\r\n```\r\n\r\n### Already cloned without submodules\r\n\r\n```sh\r\ngit submodule update --init --recursive\r\nyarn install\r\nyarn build\r\n```\r\n\r\n### Updating the submodule to the latest commit\r\n\r\n```sh\r\ngit submodule update --remote src/xpath/lib\r\n```\r\n\r\n## Tests and usage examples\r\n\r\nNew tests are written in Jest and can be run by calling: `yarn test`.\r\n\r\nThe files `xslt.html` and `xpath.html` in the directory `interactive-tests` are interactive tests. They can be run directly from the file system; no HTTP server is needed.\r\n\r\nBoth interactive tests and automatic tests demonstrate the use of the library functions.\r\n\r\n## Conformance\r\n\r\nA few features that are required by the XSLT and XPath standards were left out (but patches to add them are welcome).\r\n\r\nSee our [TODO](TODO.md) for a list of missing features that we are aware of (please add more items by means of PRs).\r\n\r\nSo far, we have implemented XQuery functions for versions 1.0 and 2.0, but this is not complete yet.\r\n\r\nThe DOM implementation is minimal so as to support the XSLT processing, and not intended to be complete.\r\n\r\nThe implementation is all agnostic about namespaces. It just expects XSLT elements to have tags that carry the `xsl:` prefix, but we disregard all namespace declarations for them.\r\n\r\n[There are a few nonstandard XPath functions](https://github.com/search?q=repo%3ADesignLiquido%2Fxslt-processor%20ext-&type=code).\r\n\r\n### HTML Conformance\r\n\r\nHTML per se is not strict XML. Because of that, starting on version 2.0.0, this library handles HTML differently than XML:\r\n\r\n- For a document to be treated as HTML, it needs to have a `` tag defined with one of the following valid formats:\r\n - `` (for HTML5);\r\n - `` (for HTML4);\r\n - `` (for XHTML 1.1).\r\n- Tags like ``, `` and `` don't need to be closed. The output for these tags doesn't close them (adding a `/` before the tag closes, or a corresponding close tag);\r\n - This rule doesn't apply for XHTML, which is strict XML.\r\n\r\n### Whitespace Handling\r\n\r\nThis library supports `xsl:strip-space` and `xsl:preserve-space` for controlling whitespace in the input document.\r\n\r\n#### `xsl:strip-space`\r\n\r\nUse `` to remove whitespace-only text nodes from specified elements in the input document:\r\n\r\n```xml\r\n\r\n \r\n \r\n\r\n \r\n \r\n\r\n \r\n\r\n```\r\n\r\nThe `elements` attribute accepts:\r\n- `*` - matches all elements\r\n- `name` - matches elements with the specified local name\r\n- `prefix:*` - matches all elements in a namespace\r\n- `prefix:name` - matches a specific element in a namespace\r\n- Multiple patterns separated by whitespace (e.g., `\"book chapter section\"`)\r\n\r\n#### `xsl:preserve-space`\r\n\r\nUse `` to preserve whitespace in specific elements, overriding `xsl:strip-space`:\r\n\r\n```xml\r\n\r\n \r\n \r\n \r\n\r\n \r\n\r\n```\r\n\r\n#### Precedence Rules\r\n\r\n1. `xml:space=\"preserve\"` attribute on an element takes highest precedence\r\n2. `xsl:preserve-space` overrides `xsl:strip-space` for matching elements\r\n3. `xsl:strip-space` applies to remaining matches\r\n4. By default (no declarations), whitespace is preserved\r\n\r\n### Breaking Changes\r\n\r\nBreaking changes are usually documented at every major release, but we also keep a short version of them below.\r\n\r\n#### Version 2\r\n\r\nUntil version 2.3.1, use like the example below:\r\n\r\n```js\r\nimport { Xslt, XmlParser } from 'xslt-processor'\r\n\r\n// xmlString: string of xml file contents\r\n// xsltString: string of xslt file contents\r\n// outXmlString: output xml string.\r\nconst xslt = new Xslt();\r\nconst xmlParser = new XmlParser();\r\nconst outXmlString = xslt.xsltProcess( // Not async.\r\n\txmlParser.xmlParse(xmlString),\r\n\txmlParser.xmlParse(xsltString)\r\n);\r\n```\r\n\r\nVersion 3 received `` which relies on Fetch API, which is asynchronous. Version 2 doesn't support ``.\r\n\r\nIf using Node.js older than version v17.5.0, please use version 3.2.3, that uses `node-fetch` package. Versions 3.3.0 onward require at least Node.js version v17.5.0, since they use native `fetch()` function.\r\n\r\n#### Version 1\r\n\r\nUntil version 1.2.8, use like the example below:\r\n\r\n```js\r\nimport { Xslt, xmlParse } from 'xslt-processor'\r\n\r\n// xmlString: string of xml file contents\r\n// xsltString: string of xslt file contents\r\n// outXmlString: output xml string.\r\nconst xslt = new Xslt();\r\nconst outXmlString = xslt.xsltProcess(\r\n\txmlParse(xmlString),\r\n\txmlParse(xsltString)\r\n);\r\n```\r\n\r\n#### Version 0\r\n\r\nUntil version 0.11.7, use like the example below:\r\n\r\n```js\r\nimport { xsltProcess, xmlParse } from 'xslt-processor'\r\n\r\n// xmlString: string of xml file contents\r\n// xsltString: string of xslt file contents\r\n// outXmlString: output xml string.\r\nconst outXmlString = xsltProcess(\r\n\txmlParse(xmlString),\r\n\txmlParse(xsltString)\r\n);\r\n```\r\n\r\nand to access the XPath parser:\r\n\r\n```js\r\nimport { xpathParse } from 'xslt-processor'\r\n```\r\n\r\nThese functions are part of `Xslt` and `XPath` classes, respectively, at version 1.x onward.\r\n\r\n## References\r\n\r\n- XPath Specification: http://www.w3.org/TR/1999/REC-xpath-19991116\r\n- XSLT Specification: http://www.w3.org/TR/1999/REC-xslt-19991116\r\n- W3C DOM Level 3 Core Specification: http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/\r\n- ECMAScript Language Specification: http://www.ecma-international.org/publications/standards/Ecma-262.htm\r\n- Arkts Language Specification: https://gitee.com/openharmony/arkcompiler_runtime_core/releases/download/ArkTS-spec-1.2.0-alpha-20250307/arktsspecification.pdf\r\n","readmeFilename":"README.md"}
![](\"https://img.shields.io/github/issues/DesignLiquido/xslt-processor\")
\r\n \r\n ![](\"https://img.shields.io/github/stars/Designliquido/xslt-processor\")
\r\n ![](\"https://img.shields.io/github/forks/Designliquido/xslt-processor\")
\r\n \r\n ![](\"https://img.shields.io/npm/v/xslt-processor\")
\r\n \r\n ![](\"https://img.shields.io/npm/dw/xslt-processor\")
\r\n ![](\"https://img.shields.io/github/license/DesignLiquido/xslt-processor\")
\r\n \r\n ![](\"https://img.shields.io/github/sponsors/leonelsanchesdasilva\")
\r\n \r\n \r\n ![](\"https://img.shields.io/badge/Buy%20Me%20a%20Coffee-orange?logo=buy-me-a-coffee\"){kind=icon}
\r\n \r\n