hnq.me
all concepts
language Updated 2026-07-09 Step 2 of 6

Directive

A beginner-friendly guide to understanding directives in UI systems.

On this page 2026-07-09
The Simple Idea Why Directives Exist Directive As Markup Logic Common UI Directives Directive vs Expression Directive vs Behavior Directive vs Component KitJS And Kitwork Notes My Learning Notes Common Misunderstandings Related Concepts

A beginner-friendly guide to directives: small instructions placed in markup so a runtime knows what behavior to attach.

A directive is a command written close to the thing it affects.

In HTML-driven UI runtimes, directives often live as attributes.

<span data-show="count > 3">Unlocked</span>

Table of Contents

The Simple Idea

A directive tells the runtime what to do with an element.

The element is normal HTML.

The directive adds runtime meaning.

Example:

<span data-show="count > 3">Unlocked</span>

The directive says:

show this element when count > 3

Why Directives Exist

Directives keep small behavior close to markup.

Instead of searching through a separate JavaScript file, you can often understand an element by reading the element.

Directives are useful for:

  • text binding,
  • visibility,
  • click actions,
  • form models,
  • validation,
  • live regions,
  • component scopes,
  • small reusable behaviors.

Directive As Markup Logic

A directive usually has two parts:

directive name + directive value

Example:

<button data-click="count = count + 1">+</button>

The name says the kind of behavior.

The value gives the expression, target, or option.

Common UI Directives

Common patterns:

<b data-text="price * quantity"></b>
<div data-show="open"></div>
<button data-click="open = !open"></button>
<input data-model="email">
<form data-validate="email.includes('@')"></form>

The exact names depend on the runtime.

The pattern is the same:

HTML carries intent
runtime reads intent
behavior appears

Directive vs Expression

The directive is the instruction.

The expression is often the logic inside it.

Example:

<b data-text="price * quantity"></b>

Here:

  • data-text is the directive,
  • price * quantity is the expression.

Directive vs Behavior

A directive declares.

A behavior performs.

Example:

<button data-action="copy" data-copy="npm install kitwork">Copy</button>

The directive tells the runtime that this button wants the copy behavior.

The behavior is the reusable code that actually copies.

Directive vs Component

A component is usually a reusable unit with state or structure.

A directive is usually a smaller instruction attached to an element.

They can work together.

A component may contain many directives.

KitJS And Kitwork Notes

Directives became real for me through KitJS. A directive was not just syntax. It was a small contract between HTML and runtime behavior.

In KitJS, directives let plain HTML express behavior: text binding, show/hide, click actions, model updates, validation, and local scope. That made markup feel programmable without turning it into a component framework.

In Kitwork, the same idea became part of a larger runtime story. A directive can be discovered by the server, hydrated by the client, and treated as something the engine can optimize, verify, or ship only when needed.

My Learning Notes

I used to think serious UI needed more JavaScript files.

Directives changed that feeling.

Some behavior is easier to understand when it stays near the HTML.

In KitJS-style runtime, markup can become the program:

HTML describes structure
directives describe behavior
runtime connects them

The lesson:

directives are bridges between markup and runtime

Common Misunderstandings

"Directives are only for frameworks."

No. Any runtime can define markup instructions.

"Directives make HTML impure."

They add behavior to HTML. Whether that is good depends on whether the runtime is clear and predictable.

"Directives replace components."

Not always. Directives and components solve different sizes of problem.

Previous: evaluate

Next: behavior

Related: expression, hydrate, blueprint

Search