Built-In Directives

Angular provides a suite of built-in directives. Some directives override built-in HTML elements, such the <form> and <a> tags. When we use tags in our HTML, it may not be immediately obvious that we are, in fact, using a directive.

For example, the <form> tag is augmented with a great deal of functionality under the hood, such as validation behavior that we normally don’t get with a standard HTML form.

Other built-in directives are clearly visible via their ng- namespace prefix. For example, ng-href, which we’ll cover below, prevents a link from becoming active until the expression provided to ng-href="someExpression" has been evaluated and returns a value.

Lastly, some built-in directives do not have an HTML counterpart, such as the ng-controller directive, which can be used as an attribute on any tag, but is most often found on an element that has many children that should share the same scope.

Note that all directives prefixed with the ng namespace are part of the built-in library of directives that ship with Angular. For this reason, never prefix directives you make with this namespace.

Basic ng Attribute Directives

Our first set of directives has similarly named standard HTML tags and is easy to remember because we simply add the ng prefix to each:

• ng-href
• ng-src
• ng-disabled
• ng-checked
• ng-readonly
• ng-selected
• ng-class
• ng-style

Boolean Attributes

The following Angular directives help make working with HTML boolean attributes easier.

As defined by the HTML specification, a boolean attribute is an attribute that represents a true/false value. When the attribute is present, then the attribute’s value is assumed to be true (regardless of its actual value). If absent, the attribute is assumed to be false.

When working with dynamic data via data bindings in Angular, we cannot simply set the value of the attribute to true or false, because by definition of the spec, the attribute is false if it is not present. Thus Angular provides an ng-prefixed version of these attributes that will evaluate the expression provided to insert or remove the corresponding boolean attribute on the decorated element.

ng-disabled

Use ng-disabled to bind the disabled attribute to form input fields:

• <input> (text, checkbox, radio, number, url, email, submit)
• <textarea>
• <select>
• <button>

When writing normal HTML input fields, the presence of the disabled attribute on an input field makes the field disabled. To bind the presence (or not) of this attribute, use ng-disabled.

For example, let’s disable the following button until the user enters text into the text field:

<input type="text" ng-model="someProperty" placeholder="Type to Enable">
<button ng-model="button" ng-disabled="!someProperty">A Button</button>

In the next example, we’ll disable the text field for five seconds until the isDisabled property becomes true inside the $timeout:

<textarea ng-disabled="isDisabled">Wait 5 seconds</textarea>

angular.module('myApp', [])
.run(function($rootScope, $timeout) {
  $rootScope.isDisabled = true;
  $timeout(function() {
    $rootScope.isDisabled = false;
  }, 5000);
});

Both Live Examples

ng-readonly

Similar to the other boolean attributes, the HTML spec only looks at the presence of the attribute readonly, not its value.

To allow Angular to bind to an expression that returns a truthy or falsy value and, in turn, output (or not) the readonly attribute, use ng-readonly:

Type here to make sibling readonly: 
<input type="text" ng-model="someProperty"><br/>
<input type="text" 
  ng-readonly="someProperty" 
  value="Some text here"/>

Live Example

ng-checked

The standard checked HTML attribute is a boolean attribute, and as such, is not required to take a value. In order for Angular to bind the presence of the checked attribute to the value of an expression, use ng-checked.

In the following example, we set the value of someProperty to true using the ng-init directive. Binding the value of someProperty to ng-checked then tells Angular to output the standard HTML checked attribute, which will check the box by default.

<label>someProperty = {{someProperty}}</label>
<input type="checkbox"
       ng-checked="someProperty"
       ng-init="someProperty = true"
       ng-model="someProperty">

In this example, we do the opposite:

<label>anotherProperty = {{anotherProperty}}</label>
<input type="checkbox"
       ng-checked="anotherProperty"
       ng-init="anotherProperty = false"
       ng-model="anotherProperty">

Note that we also used ng-model to bind the value of someProperty and anotherProperty inside their respective label tags, for the sake of demonstration.

Live Example

ng-selected

Use ng-selected to bind the presence (or not) of the selected attribute to the option tag:

<label>Select Two Fish:</label>
<input type="checkbox"
       ng-model="isTwoFish"><br/>
<select>
  <option>One Fish</option>
  <option ng-selected="isTwoFish">Two Fish</option>
</select>

Live Example

Boolean-like Attributes

While not technically HTML, boolean attributes like the ng-href and ng-src act in a similar manner and are therefore defined alongside the ng boolean attributes within the Angular source code and presented here.

Both ng-href and ng-src are so likely to help improve refactoring and prevent errors when changing code later in a project that it is recommended to use them in place of href and src, respectively.

ng-href

When dynamically creating a URL from a property on the current scope, always use ng-href instead of href.

The issue here is that the user is able to click a link built with href before interpolation takes place, which would bring them to the wrong page (often a 404).

On the other hand, by using ng-href, Angular waits for the interpolation to take place (in our example, after two seconds), and then activates the link’s behavior:

<!-- Always use ng-href when href includes an {{ expression }} -->
<a ng-href="{{myHref}}">I'm feeling lucky, when I load</a>

  <!-- href may not load before user clicks -->
<a href="{{myHref}}">I'm feeling 404</a>

Delay the interpolation of the string value for two seconds to see this behavior in action:

angular.module('myApp', [])
.run(function($rootScope, $timeout) {
  $timeout(function() {
    $rootScope.myHref = 'http://google.com';
  }, 2000);
});