Registry / serialization / hast-util-classnames

hast-util-classnames

library3.0.0jsnpmunverified

hast-util-classnames is a utility package within the unified collective, designed to simplify the management and merging of CSS class names on HAST (HTML Abstract Syntax Tree) elements. It provides a programmatic API to concatenate, conditionally include, or remove classes, analogous to popular string-based classname utilities but operating directly on HAST nodes. The package is currently at version 3.0.0, which requires Node.js 16 or higher and is distributed exclusively as an ES module (ESM). New major versions typically coincide with dropping support for unmaintained Node.js versions or significant API changes, ensuring compatibility with current Node.js releases. Its key differentiator is its deep integration with the HAST ecosystem, allowing direct manipulation of `properties.className` arrays on HAST element nodes, which is more robust than string manipulation when working with syntax trees.

serialization web-framework

npm install hast-util-classnames

github ↗package ↗

INSTALL

IMPORT

SIG · HAST-UTIL-CLASSNAM

hast-util-classnames

serializationjavascriptv3.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

classnames

✓ import { classnames } from 'hast-util-classnames';

✗ const classnames = require('hast-util-classnames');

The package became ESM-only in v2.0.0, and Node.js 16+ is required since v3.0.0.

Conditional

✓ import type { Conditional } from 'hast-util-classnames';

This type, along with `ConditionalMap` and `ConditionalPrimitive`, is useful for TypeScript consumers to correctly type arguments passed to `classnames`.

Demonstrates both ways to use `classnames`: merging an array of strings and modifying a HAST node's `className` property in place.

import {h} from 'hastscript'; import {classnames} from 'hast-util-classnames'; // Example 1: Merging class names as an array of strings const mergedClasses = classnames('alpha bravo', {bravo: false, charlie: true}, [123, 'delta']); console.log('Merged Classes (array):', mergedClasses); // Expected output: ['alpha', '123', 'charlie', 'delta'] // Example 2: Modifying classes on a HAST node in place const node = h('p.initial-class', 'Hello, HAST!'); console.log('Original Node:', JSON.stringify(node, null, 2)); const modifiedNode = classnames(node, 'new-class', {conditional: true, 'old-class': false}, ['another-one']); console.log('Modified Node:', JSON.stringify(modifiedNode, null, 2)); /* Expected output (simplified): { "type": "element", "tagName": "p", "properties": {"className": ["initial-class", "new-class", "conditional", "another-one"]}, "children": [{"type": "text", "value": "Hello, HAST!"}] } */

Debug

Known issues

breakingVersion 3.0.0 and above now require Node.js 16 or higher. Older Node.js environments are no longer supported.

fix

Upgrade your Node.js environment to version 16 or newer to ensure compatibility.

affects: >=3.0.0

breakingThe package is now exclusively an ES module (ESM) since version 2.0.0. CommonJS `require()` statements will fail.

fix

Update your import statements from `require('hast-util-classnames')` to `import { classnames } from 'hast-util-classnames';` and ensure your project is configured for ESM.

affects: >=2.0.0

breakingThe `exports` field in `package.json` was changed in v3.0.0. Directly importing non-public APIs or internal paths is no longer supported and will likely break.

fix

Only use the documented `classnames` export. Refactor any code that previously relied on internal paths to use the public API.

affects: >=3.0.0

gotchaThe `classnames` function has two distinct behaviors based on its first argument. If the first argument is a HAST `Node` (specifically an `Element`), it modifies that node's `properties.className` in place and returns the node. If the first argument is not a node (i.e., it starts with `Conditional` arguments), it returns a new `Array<string>` of merged classes.

fix

Be mindful of the function's signature and return type. If you intend to get a list of classes without modifying a node, do not pass a `Node` as the first argument. If you intend to modify a node, ensure you pass an `Element` node first.

affects: *

Errors

Common errors & fixes

ERR_REQUIRE_ESM

Attempting to import `hast-util-classnames` using CommonJS `require()` syntax.

fix

Switch to ES module import syntax: `import { classnames } from 'hast-util-classnames';`

TypeError: classnames is not a function

This error typically occurs if the package is incorrectly imported (e.g., attempting a default import `import classnames from '...'`) or if an outdated Node.js version (pre-16) is used with v3.0.0+.

fix

Ensure you are using a named import `import { classnames } from 'hast-util-classnames';` and that your Node.js version is 16 or higher for v3.0.0+.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/syntax-tree/hast-util-classnames ↗

packagehttps://www.npmjs.com/package/hast-util-classnames ↗