syntax-tree / hast-util-classnames

utility to merge class names together

hast-util-classnames

hast utility to set classes.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • classnames([node, ]…conditionals)
  • ConditionalPrimitive
  • ConditionalMap
  • Conditional
• Types
• Compatibility
• Security
• Related
• Contribute
• License

What is this?

This package is a utility that takes lets you more easily set class names on elements.

When should I use this?

You can use this package when you find that that you’re repeating yourself a lot when working with classes in the syntax tree.

Install

This package is ESM only. In Node.js (version 16+), install with npm:

npm install hast-util-classnames

In Deno with esm.sh:

import {classnames} from 'https://esm.sh/hast-util-classnames@3'

In browsers with esm.sh:

<script type="module">
  import {classnames} from 'https://esm.sh/hast-util-classnames@3?bundle'
</script>

Use

import {h} from 'hastscript'
import {classnames} from 'hast-util-classnames'

console.log(classnames('alpha bravo', {bravo: false}, [123, 'charlie']))

const node = h('p.alpha', 'Hi!')
console.log(classnames(node, 'bravo', ['charlie', {delta: false, echo: 1}]))

Yields:

['alpha', '123', 'charlie']
{
  type: 'element',
  tagName: 'p',
  properties: {className: ['alpha', 'bravo', 'charlie', 'echo']},
  children: [{type: 'text', value: 'Hi!'}]
}

API

This package exports the identifier classnames. There is no default export.

classnames([node, ]…conditionals)

Merge classes.

This function has two signatures, depending on whether a node was passed.

Signatures

• (node: Node, ...conditionals: Array<Conditional>) => Node
• (...conditionals: Array<Conditional>) => Array<string>

Parameters

• node (Node) — optionally, node whose classes to append to (must be Element)
• conditionals (Array<Conditional>) — class configuration to merge

Returns

The given node (Node), if any, or a list of strings (Array<string>).

ConditionalPrimitive

Basic class names (TypeScript type).

Type

type ConditionalPrimitive = number | string

ConditionalMap

Map of class names as keys, with whether they’re turned on or not as values.

Type

type ConditionalMap = Record<string, boolean>

Conditional

Different ways to turn class names on or off (TypeScript type).

Type

type Conditional =
  | Array<
      | Array<ConditionalPrimitive | ConditionalMap>
      | ConditionalMap
      | ConditionalPrimitive
    >
  | ConditionalMap
  | ConditionalPrimitive
  | null
  | undefined

Types

This package is fully typed with TypeScript. It exports the additional types Conditional, ConditionalMap, and ConditionalPrimitive.

Compatibility

Projects maintained by the unified collective are compatible with maintained versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line, hast-util-classnames@^3, compatible with Node.js 16.

Security

Classes are typically not harmful, however, if someone were able to inject classes, it could mean that user-provided content looks like official content, which may cause security problems due to impersonation. Either do not use user input in classnames or use hast-util-sanitize to clean the tree.

Related

• hastscript — create hast trees
• hast-util-from-selector — parse CSS selectors to hast nodes
• hast-util-has-property — check if a node has a property
• hast-util-is-element — check if a node is a (certain) element

Contribute

See contributing.md in syntax-tree/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer