Directive Overview

Directives are how AngularTS attaches behavior and structure to HTML. A directive is a marker on a DOM element or attribute that tells $compile to attach behavior, transform DOM, wire events, create scopes, or connect controllers.

Every built-in directive in AngularTS is applied as an HTML attribute using the ng- prefix. The compiler normalizes prefixes, so ng-bind, data-ng-bind, and x-ng-bind all match the same directive.

Exact custom directive contracts live in TypeDoc:

• Directive
• DirectiveFactory
• DirectiveFactoryFn
• Component
• CompileFn
• PublicLinkFn
• TranscludeFn

How Directives Are Matched

The restrict option controls where a directive can appear.

Attribute directives are the common case in AngularTS. They keep the host element in place and augment it.

Built-In Directive Groups

AngularTS groups its built-in directives by the user-facing job they perform. Keep these groups in mind when choosing where to look in the docs.

Create A Custom Directive

Register directives on a module with .directive(name, factory). The factory returns a directive definition object.

angular.module("demo", []).directive("highlight", () => {
  return {
    restrict: "A",
    scope: {
      color: "@highlight",
    },
    link(scope, element) {
      const paint = (color) => {
        element.style.backgroundColor = color || "yellow";
      };

      paint(scope.color);

      scope.$watch("color", paint);
    },
  };
});

<p highlight="gold">Pinned note</p>

Use compile() when the directive must transform template DOM before linking. Use link() when it only needs to attach behavior to each compiled instance.

Execution Order

When multiple directives appear on the same element, AngularTS sorts them by priority from highest to lowest. Directives with equal priority run in registration order.

<li ng-repeat="item in items" ng-class="{ active: item.selected }">
  {{ item.name }}
</li>

Structural directives such as ng-repeat and ng-if use high priorities and terminal behavior because they replace or remove DOM before lower-priority directives are linked.

Scope Choice

Use the default inherited scope for simple behavior. Create a child scope when the directive needs local state. Use isolate scope bindings when the directive is designed as a reusable widget with explicit inputs and callbacks.

scope: {
  title: "@",
  value: "=",
  onSave: "&",
}

Prefer components for larger reusable UI pieces. Use directives for behaviors, DOM integrations, structural transforms, and lightweight element coordination.

Next Steps

• Data binding
• Structural directives
• Form directives
• HTTP directives