Creating directives in AngularJS is accomplished with a directive definition object. This object, which is returned from the definition function, contains various properties that serve to shape how a directive will act in your application.

You can build a simple custom element directive easily with the following code:

(app.js)

// application module definition
angular.module('myApp', [])
.directive('myDirective', function() {
  // return the directive definition object
  return {
    // only match this directive to element tags
    restrict: 'E',
    // insert the template matching 'my-template.html'
    templateUrl: 'my-template.html'
  };
});

As you might have guessed, it's bad practice to define your directive template with the template property unless it is very small, so this example will skip right to what you will be using in production: templateUrl and $templateCache. For this recipe, you'll use a relatively simple template, which can be added to $templateCache using ng-template. An example application will appear as follows:

(index.html)

<!-- specify root element of application -->
<div ng-app="myApp">
  <!-- register 'my-template.html' with $templateCache -->
  <script type="text/ng-template" id="my-template.html">
    <div ng-repeat="num in [1,2,3,4,5]">{{ num }}</div>
  </script>  
  
  <!-- your custom element -->
  <my-directive></my-directive>
</div>

When AngularJS encounters an instance of a custom directive in the index.html template, it will compile the directive into HTML that makes sense to the browser, which will look as follows:

<div>1</div>
<div>2</div>
<div>3</div>
<div>4</div>
<div>5</div>

The restrict: 'E' statement indicates that your directive will appear as an element. It simply instructs AngularJS to search for an element in the DOM that has the my-directive tag.

Especially in the context of directives, you should always think of AngularJS as an HTML compiler. AngularJS traverses the DOM tree of the page to look for directives (among many other things) that it needs to perform an action for. Here, AngularJS looks at the <my-directive> element, locates the relevant template in $templateCache, and inserts it into the page for the browser to handle. The provided template will be compiled in the same way, so the use of ng-repeat and other AngularJS directives is fair game, as demonstrated here.

A directive in this fashion, though useful, isn't really what directives are for. It provides a nice jumping-off point and gives you a feel of how it can be used. However, the purpose that your custom directive is serving can be better implemented with the built-in ng-include directive, which inserts a template into the designated part of HTML. This is not to say that directives shouldn't ever be used this way, but it's always good practice to not reinvent the wheel. Directives can do much more than template insertion (which you will soon see), and it's best to leave the simple tasks to the tools that AngularJS already provides to you.

All directives are able to define a link function, which defines how that particular directive instance will interact with the part of the DOM it is attached to. The link functions have three parameters by default: the directive scope (which you will learn more about later), the relevant DOM element, and the element's attributes as key-value pairs.

A directive can exist in a template in four different ways: as an HTML pseudo-element, as an HTML element attribute, as a class, and as a comment.

(index.html)

<div ng-app="myApp">
  <element-directive some-attr="myvalue">
    <!-- directive's HTML contents -->
  </element-directive>
</div>

(app.js)

angular.module('myApp', [])
.directive('elementDirective', function ($log) {
  return {
    restrict: 'E',
    template: '<p>Ze template!</p>',
    link: function(scope, el, attrs) {
      $log.log(el.html());
      // <p>Ze template!</p>
      $log.log(attrs.someAttr);
      // myvalue
    }
  };
});

(index.html)

angular.module('myApp', [])
.directive('elementDirective', function ($log) {
  return {
    restrict: 'E',
    replace: true,
    template: '<p>Ze template!</p>',
    link: function(scope, el, attrs) {
      $log.log(el.html());
      // Ze template!
      $log.log(attrs.someAttr);
      // myvalue
    }
  };
});

(index.html)

<div ng-app="myApp">
  <div attribute-directive="aval" 
     some-attr="myvalue">
  </div>
</div>

(app.js)

angular.module('myApp', [])
.directive('attributeDirective', function ($log) {
  return {
    // restrict defaults to A
    restrict: 'A', 
    template: '<p>An attribute directive</p>',
    link: function(scope, el, attrs) {
      $log.log(el.html());
      // <p>An attribute directive</p>
      $log.log(attrs.attributeDirective);
      // aval
      $log.log(attrs.someAttr);
      // myvalue
    }
  };
});

(index.html)

<div ng-app="myApp">
  <div class="class-directive: cval; normal-class" 
       some-attr="myvalue">
  </div>
</div>

(app.js)

angular.module('myApp', [])
.directive('classDirective', function ($log) {
  return {
    restrict: 'C',
    template: '<p>A class directive</p>',
    link: function(scope, el, attrs) {
      $log.log(el.html());
      // <p>A class directive</p>
      $log.log(el.hasClass('normal-class'));
      // true
      $log.log(attrs.classDirective);
      // cval
      $log.log(attrs.someAttr);
      // myvalue
    }
  };
});

(index.html)

<div ng-app="myApp">
  <!-- directive: comment-directive val1 val2 val3 -->
</div>

(app.js)

angular.module('myApp', [])
.directive('commentDirective', function ($log) {
  return {
    restrict: 'M',
    // without replace: true, the template cannot
    // be inserted into the DOM 
    replace: true,
    template: '<p>A comment directive</p>',
    link: function(scope, el, attrs) {
      $log.log(el.html()) 
      // <p>A comment directive</p>
      $log.log(attrs.commentDirective) 
      // 'val1 val2 val3'
    }
  };
});

AngularJS actively compiles the template, searching for matches to defined directives. It's possible to chain directive forms together within the same definition. The mydir directive with restrict: 'EACM' can appear as follows:

<mydir></mydir>

<div mydir></div>

<div class="mydir"></dir>

<!-- directive: mydir -->

The $log.log() statements in this recipe should have given you some insight into the extraordinary use that directives can have in your application.

The far more common use case of directives is to create them as an HTML element attribute (this is the default behavior for restrict). As you can imagine, this allows us to decorate existing material in the DOM, as follows:

(app.js)

angular.module('myApp', [])
.directive('counter', function () {
  return {
    restrict: 'A',
    link: function (scope, el, attrs) {
      // read element attribute if it exists
      var incr = parseInt(attrs.incr || 1)
        , val = 0;
      // define callback for vanilla DOM click event
      el.bind('click', function () {
        el.html(val += incr);
      });
    }
  };
});

This directive can then be used on a <button> element as follows:

(index.html)

<div ng-app="myApp">
  <button counter></button>
  <button counter incr="5"></button>
</div>

AngularJS includes a subset of jQuery (dubbed jqLite) that lets you use a core toolset to modify the DOM. Here, your directive is attached to a singular element that the directive sees in its linking function as the element parameter. You are able to define your DOM modification logic here, which includes initial element modification and the setup of events.

In this recipe, you are consuming a static attribute value incr inside the link function as well as invoking several jqLite methods on the element. The element parameter provided to you is already packaged as a jqLite object, so you are free to inspect and modify it at your will. In this example, you are manually increasing the integer value of a counter, the result of which is inserted as text inside the button.

Here, it's important to note that you will never need to modify the DOM in your controller, whether it is a directive controller or a general application controller. Because AngularJS and JavaScript are very flexible languages, it's possible to contort them to perform DOM manipulation. However, managing the DOM transformation out of place causes an undesirable dependency between the controller and the DOM (they should be totally decoupled) as well as makes testing more difficult. Thus, a well-formed AngularJS application will never modify the DOM in controllers. Directives are tailor-made to layer and group DOM modification tasks, and you should have no trouble using them as such.

Additionally, it's worth mentioning that the attrs object is read-only, and you cannot set attributes through this channel. It's still possible to modify attributes using the element attribute, but state variables for elements can be much more elegantly implemented, which will be discussed in a later recipe.

The following directive will display NW, NE, SW, or SE depending on where the cursor is relative to it:

angular.module('myApp', [])
.directive('vectorText', function ($document) {
  return {
    template: '<span>{{ heading }}</span>',
    link: function (scope, el, attrs) {

      // initialize the css
      el.css({
        'float': 'left',
        'padding': attrs.buffer+"px"
      });

      // initialize the scope variable
      scope.heading = '';

      // set event listener and handler
      $document.on('mousemove', function (event) {
        // mousemove event does not start $digest,
        // scope.$apply does this manually
        scope.$apply(function () {
          if (event.pageY < 300) {
            scope.heading = 'N';
          } else {
            scope.heading = 'S';
          }
          if (event.pageX < 300) {
            scope.heading += 'W';
          } else {
            scope.heading += 'E';
          }
        });
      });
    }
  };
});

This directive will appear in the template as follows:

(index.html)

<div ng-app="myApp">
  <div buffer="300" 
       vector-text>
  </div>
</div>

This directive has a lot more to wrap your head around. You can see that it has $document injected into it, as you need to define event listeners relevant to this directive all across $document. Here, a very simple template is defined, which would preferably be in its own file, but for the sake of simplicity, it is merely incorporated as a string.

This directive first initializes the element with some basic CSS in order to have the relevant anchor point somewhere you can move the cursor around fully. This value is taken from an element attribute in the same fashion it was used in the previous recipe.

Here, our directive is listening to a $document mousemove event, with a handler inside wrapped in the scope.$apply() wrapper. If you remove this scope.$apply() wrapper and test the directive, you will notice that while the handler code does execute, the DOM does not get updated. This is because the event that the application is listening for does not occur in the AngularJS context—it is merely a browser DOM event, which AngularJS does not listen for. In order to inform AngularJS that models might have been altered, you must utilize the scope.$apply() wrapper to trigger the update of the DOM.

With all of this, your cursor movement should constantly be invoking the event handler, and you should see a real-time description of your cursor's relative cardinal locality.

In this directive, we have used the scope parameter for the first time. You might be wondering, "Which scope am I using? I haven't declared any specific scope anywhere else in the application." Recall that a directive will inherit a scope unless otherwise specified, and this recipe is no different. If you were to inject $rootScope to the directive and log to the $rootScope.heading console inside the event handler, you would see that this directive is writing to the heading attribute of the $rootScope of the entire application!

For this recipe, assume your directive exists inside the following setup:

(index.html)

<div ng-app="myApp">
  <div ng-controller="MainCtrl">
    <div iso></div>
  </div>
</div>

(app.js)

angular.module('myApp', [])
.controller('MainCtrl', function ($log, $scope) {
  $scope.outerval = 'mydata';
  $scope.func = function () {
    $log.log('invoked!');
  };
})
.directive('iso', function () {
  return {};
});

To declare a directive with an isolate scope, simply pass an empty object literal as the scope property:

(app.js)

.directive('iso', function () {
  return {
    scope: {}
  };
});

With this, there will be no inheritance from the parent scope in MainCtrl, and the directive will be unable to use methods or variables in the parent scope.

If you want to pass a read-only value to the directive, you will use @ inside the isolate scope declaration to indicate that a named attribute of the relevant HTML element contains a value that should be incorporated into the directive's isolate scope. This can be done as follows:

(index.html)

<div ng-app="myApp">
  <div ng-controller="MainCtrl">
    <div>Outer: {{ outerval }}</div>
    <div iso myattr="{{ outerval }}"></div>
  </div>
</div>

(app.js)

.directive('iso', function () {
  return {
    template: 'Inner: {{ innerval }}',
    scope: {
      innerval: '@myattr'
    }
  };
});

With this, the scope inside the directive now contains an innerval attribute with the value of outerval in the parent scope. AngularJS evaluates the expression string, and the result is provided to the directive's scope. Setting the value of the variable does nothing to the parent scope or the attribute in the HTML; it is merely copied into the scope of the directive.

While this approach is useful, it doesn't involve data binding, which you have come to love in AngularJS, and it isn't all that more convenient than passing in a static string value. What is far more likely to be useful to you is a true whitelist of the data binding from the parent scope. This can be accomplished with the = definition, as follows:

(index.html)

<div ng-app="myApp">
  <div ng-controller="MainCtrl">
    <div>Outer: {{ outerval }}</div>
    <div iso myattr="outerval"></div>
  </div>
</div>

(app.js)

.directive('iso', function () {
  return {
    template: 'Inner: {{ innerval }}',
    scope: {
      innerval: '=myattr'
    }
  };
});

Here, you are instructing the child directive scope to examine the parent controller scope, and bind the parent outerval attribute inside the child scope, aliased as the innerval attribute. Full data binding between scopes is supported, and all unnamed attributes and methods in the parent scope are ignored.

Taking a step further, methods can also be pulled down from the parent scope for use in the directive. In the same way that a model variable can be bound to the child scope, you can alias methods that are defined in the parent scope to be invoked from the child scope but are still in the parent scope context. This is accomplished with the & definition, as follows:

(index.html)

<div ng-app="myApp">
  <div ng-controller="MainCtrl">
    <div iso myattr="func()"></div>
  </div>
</div>

(app.js)

.directive('iso', function () {
  return {
    scope: {
      innerval: '&myattr'
    },
    link: function(scope) {
      scope.innerval();
      // invoked!  
    }
  };
});

Here, you are instructing the child directive to evaluate the expression passed to the myattr attribute within the context of the parent controller. In this case, the expression will invoke the func() method, but any valid AngularJS expression will also work. You can invoke it as you would invoke any other scope method, including parameters as required.

Isolate scope is entirely managed within the scope attribute in the directive's returned definition object. Using @, =, and &, you are instructing the directive to ignore the scopes it would normally inherit, and only utilize data, variables, and methods that you have provided interfaces for instead.

If the directive is designed as a specific modifier for an aspect of your application, you might find that using isolate scope isn't necessary. On the other hand, if you're building a reusable, monolithic component that can be reused across multiple applications, it is unlikely that the directive will be using the parent scope in which it is used. Hence, isolate scope will be significantly more useful.

For this recipe, suppose that your application template includes the following:

(index.html)

<div ng-app="myApp">
  <div parent-directive>
    <div child-directive 
         sibling-directive>
    </div>
  </div>
</div>

Inter-directive communication is accomplished with the require attribute, as follows:

return {
  require: ['^parentDirective', '^siblingDirective'],
  link: function (scope, el, attrs, ctrls) {
    $log.log(ctrls);
    // logs array of in-order required controller objects
  }
};

Using the stringified directive names passed through require, AngularJS will examine the current and parent HTML elements that match the directive names. The controller objects of these directives will be returned in an array as the ctrls parameter in the original directive's link function.

These directives can expose methods as follows:

(app.js)
angular.module('myApp', [])
.directive('parentDirective', function ($log) {
  return {
    controller: function () {
      this.identify = function () {
        $log.log('Parent!');
      };
    }
  };
})
.directive('siblingDirective', function ($log) {
  return {
    controller: function () {
      this.identify = function () {
        $log.log('Sibling!');
      };
    }
  };
})
.directive('childDirective', function ($log) {
  return {
    require: ['^parentDirective', '^siblingDirective'],
    link: function (scope, el, attrs, ctrls) {
      ctrls[0].identify();
      // Parent!
      ctrls[1].identify();
      // Sibling!
    }
  };
});

The childDirective fetches the requested controllers and passes them to the link function, which can use them as regular JavaScript objects. The order in which directives are defined is not important, but the controller objects will be returned in the order in which they are requested.

Suppose that your application includes the following:

(index.html)

<div ng-app="myApp">
  <div parent-directive>
    <div child-directive 
         sibling-directive>
    </div>
  </div>
</div>

(app.js)

angular.module('myApp', [])
.directive('parentDirective', function ($log) {
  return {
    controller: function () {
      this.identify = function () {
        $log.log('Parent!');
      };
    }
  };
})
.directive('siblingDirective', function ($log) {
  return {
    controller: function () {
      this.identify = function () {
        $log.log('Sibling!');
      };
    }
  };
});

Note that in index.html, the missingDirective is not present. A ? prefixed to the require array element denotes an optional controller directive. This is shown in the following code:

(app.js)

.directive('childDirective', function ($log) {
  return {
    require: [
      '^parentDirective',
      '^siblingDirective',
      '^?missingDirective'
    ],
    link: function (scope, el, attrs, ctrls) {
      ctrls[0].identify();
      // Parent!
      ctrls[1].identify();
      // Sibling!
      $log.log(ctrls[2]);
      // null
    }
  };
});

If the controller exists, it will be served in the same fashion as the others. If not, the returned array will be a null value at the corresponding index.

An AngularJS controller is merely a JavaScript constructor function, and when parentDirective and siblingDirective are required, each directive returns their controller object. As you are using the controller object and not the controller scope, you must define your public controller methods on this instead of $scope. The $scope doesn't make sense in the context of a foreign directive—recall that the directive is in the process of being linked when all of this happens.

Suppose that you begin with the following skeleton application:

(index.html - uncompiled)

<div ng-app="myApp">
  <div ng-controller="MainCtrl">
    <my-directive>
      <p>HTML template</p>
      <p>Scope from {{origin}}</p>
      <p>Overwritten? {{overwrite}}</p>
    </my-directive>
  </div>
</div>

(app.js)

angular.module('myApp', [])
.controller('MainCtrl', function ($scope) {
  $scope.overwrite = false;
  $scope.origin = 'parent controller';
});

The most basic setup is to have the directive scope inherit from the parent scope that will be used by the directive within the link function. This allows the directive to manipulate the parent scope. This can be done as follows:

(app.js)

.directive('myDirective', function () {
  return {
    restrict: 'E',
    link: function (scope) {
      scope.overwrite = !!scope.origin;
      scope.origin = 'link function';
    }
  };
});

This will compile into the following:

(index.html – compiled)

<my-directive>
  <p>HTML template</p>
  <p>Scope from link function</p>
  <p>Overwritten? true</p>
</my-directive>

There's nothing tricky going on here. The directive has no template, and the HTML inside it is subject to the modifications that the link function makes to the scope. As this does not use isolate scope and there is no transclusion, the parent scope is provided as the scope parameter, and the link function writes to the parent scope's models. The HTML output tells us that the template was rendered from our index.html markup, the link function was the last to modify the scope, and the link function overwrote the original values set up in the parent controller.

Suppose that you begin with the following skeleton application:

(index.html - uncompiled)

<div ng-app="myApp">
  <div ng-controller="MainCtrl">
    <my-directive>
      Stuff inside
    </my-directive>
  </div>
</div>

(app.js)

angular.module('myApp', [])
.controller('MainCtrl', function ($scope) {
  $scope.overwrite = false;
  $scope.origin = 'parent controller';
});

Introduce a template to the directive as follows:

(index.html – uncompiled)

<div ng-app="myApp">
  <div ng-controller="MainCtrl">
    <my-directive>
      Stuff inside
    </my-directive>
  </div>
  
  <script type="text/ng-template" id="my-directive.html">
    <div>
      <p>Directive template</p>
      <p>Scope from {{origin}}</p>
      <p>Overwritten? {{overwrite}}</p>
    </div>
  </script>
</div>

(app.js)

angular.module('myApp', [])
.controller('MainCtrl', function ($scope) {
  $scope.overwrite = false;
  $scope.origin = 'parent controller';
})
.directive('myDirective', function() {
  return {
    restrict: 'E',
    replace: true,
    templateUrl: 'my-directive.html',
    link: function (scope) {
      scope.overwrite = !!scope.origin;
      scope.origin = 'link function';
    }
  };
});

This snippet will compile the directive element into the following:

(index.html – compiled)

<div>
  <p>Directive template</p>
  <p>Scope from link function</p>
  <p>Overwritten? true</p>
</div>

The parent scope from MainCtrl is inherited by the directive and is provided as the scope parameter inside the directive's link function. The directive template is inserted to replace the <my-directive> tag and its contents, but the supplanting template HTML is still subject to the inherited scope. The link function is able to modify the parent scope as though it were the directive's own. In other words, the link scope and the controller scope are the same object in this example.

Suppose that you begin with the following skeleton application:

(index.html - uncompiled)

<div ng-app="myApp">
  <div ng-controller="MainCtrl">
    <my-directive>
      Stuff inside
    </my-directive>
  </div>
  
  <script type="text/ng-template" id="my-directive.html">
    <div>
      <p>Directive template</p>
      <p>Scope from {{origin}}</p>
      <p>Overwritten? {{overwrite}}</p>
    </div>
  </script>
</div>

(app.js)

angular.module('myApp', [])
.controller('MainCtrl', function ($scope) {
  $scope.overwrite = false;
  $scope.origin = 'parent controller';
});

Assign an isolate scope to the directive with an empty object literal, as follows:

(app.js)

.directive('myDirective', function() {
  return {
    templateUrl: 'my-directive.html',
    replace: true,
    scope: {},
    link: function (scope) {
      scope.overwrite = !!scope.origin;
      scope.origin = 'link function';
    }
  };
});

This will compile into the following:

(index.html – compiled)

<div>
  <p>Directive template</p>
  <p>Scope from link function</p>
  <p>Overwritten? false</p>
</div>

The directive creates its own scope and performs the modifications on the scope instead of performing them inside the link function. The parent scope is unchanged and obscured from inside the directive's link function.