StyleBinder.js

StyleBinder is a browser JavaScript Singleton class designed to bind class names to elements via CSS style rules rather than the inline class attribute.

StyleBinder is for teams who want CSS to declare intent and JavaScript to enforce structure, without polluting markup or inventing a framework.

Why StyleBinder?

CSS is excellent at expressing intent, but it cannot directly apply classes. StyleBinder bridges that gap by allowing CSS to declare which classes should exist, while JavaScript enforces that structure at runtime.

No new syntax. No framework. The CSS cascade decides; JavaScript reacts.

Quick Example

CSS

article h2 {
  --style-binder-classes: header emphasized;
  --style-binder-included-tags: h2;
}

HTML Code

<article>
  <h2>Hello</h2>
</article>

Resulting HTML In the Browser

<article>
    <h2 class="header emphasized">Hello</h2>
</article>

Operation & Usage

At runtime, StyleBinder observes DOM additions under a specified root element (the document element by default). For each new element, its computed style is queried for the following variables, and the corresponding action is taken.

StyleBinder variables follow standard CSS cascade rules. If a variable is declared multiple times, the final computed value wins.

Variable Name	Action
--style-binder-classes	Add these classes to the selected element's class list.
--style-binder-included-tags	Apply the class list only to these element tags.
--style-binder-excluded-tags	Apply the class list to all element tags except these.

Use Cases

Custom HTML Tags

Custom HTML tags are useful for structure and semantics, but they do not allow class composition inside CSS alone. Without StyleBinder, developers must either:

• Add classes directly in markup, or
• Create redundant selectors that duplicate intent

StyleBinder allows class composition to be expressed directly in CSS style rules, without touching the element’s class attribute.

Non-Goals

StyleBinder does not:

• Remove classes
• Merge multiple rule values
• Replace CSS selectors
• Act as a component framework

It is intentionally additive, declarative, and minimal.

Limitations

Because StyleBinder uses CSS variables, those variables participate in normal CSS inheritance. As a result, variables may be visible to elements deeper in the DOM tree than intended.

CSS selectors should be used for primary targeting. The included and excluded tag lists provide additional scope refinement without requiring extra selectors.

Philosophy

StyleBinder respects the CSS cascade. CSS declares intent. JavaScript enforces structure.

Nothing more.