XPath to CSS Selector Converter

Common errors

• TypeError: xPathToCss is not a function

  cause Attempting to import `xPathToCss` as a named export (`import { xPathToCss } from 'xpath-to-css';`) when it is a default export, or using incorrect CommonJS destructuring.
  fix For ES Modules, use `import xPathToCss from 'xpath-to-css';`. For CommonJS, use `const xPathToCss = require('xpath-to-css');`.

• Error: Unsupported XPath expression: //some/complex/xpath[contains(text(), 'value')]/parent::*

  cause The provided XPath expression uses features or patterns that the `xpath-to-css` library cannot translate into a CSS selector. Not all XPath constructs have direct CSS equivalents (e.g., parent traversal, complex text matching functions).
  fix Simplify the XPath expression if possible to use only commonly supported features (IDs, classes, attributes, direct child/descendant, position). If simplification is not feasible, consider manually crafting a CSS selector or using alternative element location strategies for the problematic part. Verify if the XPath expression is valid and if a CSS equivalent can exist.

Warnings

• gotcha Not all advanced or complex XPath expressions can be directly translated into equivalent CSS selectors. The utility might return an error or an incomplete selector for XPath features like parent traversal (`..`), preceding-sibling, or complex text content matching not based on `contains()`.
  Fix: Simplify the XPath expression if possible, or manually craft a CSS selector or alternative locator strategy for the problematic part. Understand the limitations of CSS selectors compared to XPath.
• gotcha The conversion process is synchronous. While generally fast for typical XPath expressions, for applications requiring high performance or processing a very large number of extremely complex XPath expressions, this might introduce blocking delays.
  Fix: Consider batching conversions, offloading to a worker thread for very high-volume scenarios, or pre-converting known XPaths during application startup if performance becomes an issue.
• gotcha The package appears to be in maintenance mode, with its last update over two years ago and no recent releases. While stable for its current functionality, new XPath features or complex edge cases introduced in newer browser standards may not be supported or actively developed.
  Fix: Review the package's GitHub issues for known limitations or unaddressed features before relying on it for cutting-edge XPath patterns. Be prepared to contribute fixes or fork if specific unsupported features are critical.

Install

• npm install xpath-to-css npm
• yarn add xpath-to-css yarn
• pnpm add xpath-to-css pnpm

Imports

• xPathToCss
  wrong:

  import { xPathToCss } from 'xpath-to-css';

  correct:

  import xPathToCss from 'xpath-to-css';

  The primary conversion function is exported as a default export in ES Modules.
• xPathToCss (CommonJS)
  wrong:

  const { xPathToCss } = require('xpath-to-css');

  correct:

  const xPathToCss = require('xpath-to-css');

  For CommonJS environments, `require` directly returns the default-exported function, no `.default` or destructuring is needed.

Quickstart

Demonstrates how to import the `xPathToCss` function and convert a complex XPath expression to its CSS selector equivalent, along with simpler examples.

import xPathToCss from 'xpath-to-css';

const xPath = '//div[@id="foo"][2]/span[@class="bar"]//a[contains(@class, "baz")]//img[1]';
const css = xPathToCss(xPath);
console.log(css); // => 'div#foo:nth-of-type(2) > span.bar a[class*=baz] img:first-of-type'

const simpleXPath = '//h1';
const simpleCss = xPathToCss(simpleXPath);
console.log(simpleCss); // => 'h1'

const attributeXPath = '//input[@type="text"]';
const attributeCss = xPathToCss(attributeXPath);
console.log(attributeCss); // => 'input[type="text"]'