AngularJS: ngInclude vs directive

It all depends on what you want from your code fragment. Personally, if the code doesn’t have any logic, or doesn’t even need a controller, then I go with ngInclude. I typically put large more “static” html fragments that I don’t want cluttering up the view here. (ie: Let’s say a large table whose data comes from the parent Controller anyway. It’s cleaner to have <div ng-include="bigtable.html" /> than all those lines cluttering up the View)

If there is logic, DOM manipulation, or you need it to be customizable (aka render differently) in different instances it’s used, then directives are the better choice (they’re daunting at first, but they’re very powerful, give it time).


Sometimes you will see ngInclude's that are affected by their exterior $scope / interface. Such as a large/complicated repeater lets say. These 2 interfaces are tied together because of this. If something in the main $scope changes, you must alter / change your logic within your included partial.


On the other hand, directives can have explicit scopes / controllers / etc. So if you’re thinking of a scenario where you’d have to reuse something multiple times, you can see how having its own scope connected would make life easier & less confusing.

Also, anytime you are going to be interacting with the DOM at all, you should use a directive. This makes it better for testing, and decouples these actions away from a controller / service / etc, which is something you want!

Tip: Make sure not to use restrict: ‘E’ if you care about IE8! There are ways around this, but they are annoying. Just make life easier and stick with attribute/etc. <div my-directive />

Components [Update 3/1/2016]

Added in Angular 1.5, it’s essentially a wrapper around .directve(). Component should be used most of the time. It removes a lot of boilerplate directive code, by defaulting to things like restrict: 'E', scope : {}, bindToController: true. I highly recommend using these for almost everything in your app, in order to be able to transition to Angular2 more easily.

In conclusion:

You should be creating Components & Directives a majority of the time.

  • More extensible
  • You can template and have your file externally (like ngInclude)
  • You can choose to use the parent scope, or it’s own isolate scope within the directive.
  • Better re-use throughout your application

Update 3/1/2016

Now that Angular 2 is slowly wrapping up, and we know the general format (of course there will still be some changes here and there) just wanted to add how important it is to do components (sometimes directives if you need them to be restrict: ‘E’ for example).

Components are very similar to Angular 2’s @Component. In this way we are encapsulating logic & html in the same area.

Make sure you encapsulate as many things as you can in components, it will make the transition to Angular 2 that much easier! (If you choose to make the transition)

Here’s a nice article describing this migration process using directives (very similar if you were going to use components of course) :

Leave a Comment