Become a ninja with Angular

The sixth version of the specification reached its final state in 2015. So it’s now supported by modern browsers, but there are still browsers in the wild that don’t support it yet, or only support it partially. And of course, now that we have a new specification every year (ES2016, ES2017, etc.), some browsers will always be late. You might be thinking: what’s the point of all this, if I need to be careful on what I can use? And you’d be right, because there aren’t that many apps that can afford to ignore older browsers. But, since virtually every JS developer who has tried ES2015+ wants to write ES2015+ apps, the community has found a solution: a transpiler.

A transpiler takes ES2015+ source code and generates ES5 code that can run in every browser. It even generates the source map files, which allows you to debug directly the ES2015+ source code from the browser. Back in 2015, there were two main alternatives to transpile ES2015+ code:

The source code of Angular itself was at first transpiled with Traceur, before switching to TypeScript. TypeScript is an open source language developed by Microsoft. It’s a typed superset of JavaScript that compiles to plain JavaScript, but we’ll dive into it very soon.

Let’s be honest: Babel has waaaay more steam than Traceur nowadays, so I would advise you to use it. It is now the de-facto standard in this area.

So if you want to play with ES2015+, or set it up in one of your projects, take a look at these transpilers, and add a build step to your process. It will take your ES2015+ source files and generate the equivalent ES5 code. It works very well but, of course, some of the new features are quite hard or impossible to transform in ES5, as they just did not exist. However, the current state is largely good enough for us to use without worrying, so let’s have a look at all these shiny new things we can do in JavaScript!

If you have been writing JS for some time, you know that the var declaration is tricky. In pretty much any other language, a variable is declared where the declaration is done. But in JS, there is a concept, called "hoisting", which actually declares a variable at the top of the function, even if you declared it later.

So declaring a variable like name in the if block:

is equivalent to declaring it at the top of the function:

ES2015 introduces a new keyword for variable declaration, let, behaving much more like what you would expect:

The variable name is now restricted to its block. let has been introduced to replace var in the long run, so you can pretty much drop the good old var keyword and start using let instead. The cool thing is, it should be painless to use let, and if you can’t, you have probably spotted something wrong with your code!

Since we are on the topic of new keywords and variables, there is another one that can be of interest. ES2015 introduces const to declare…​ constants! When you declare a variable with const, it has to be initialized and you can’t assign another value later.

As for variables declared with let, constants are not hoisted and are only declared at the block level.

One small thing might surprise you: you can initialize a constant with an object and later modify the object content.

But you can’t assign another object:

Same thing with arrays:

Not a new keyword, but it can also catch your attention when reading ES2015 code. There is now a shortcut for creating objects, when the object property you want to create has the same name as the variable used as the value.

Example:

can be simplified to:

Similarly, when you want to define a method in the object:

you can simplify it to:

This new feature can also catch your attention when reading ES2015 code. There is now a shortcut for assigning variables from objects or arrays.

In ES5:

Now, in ES2015, you can do:

And you will have the same result. It can be a little disturbing, as the key is the property to look for in the object and the value is the variable to assign. But it works great! Even better: if the variable you want to assign has the same name as the property, you can simply write:

The cool thing is that it also works with nested objects:

And the same is possible with arrays:

Of course it also works for arrays in arrays, or arrays in objects, etc.

One interesting use of this can be for multiple return values. Imagine a function randomPonyInRace that returns a pony and its position in a race.

The new destructuring feature assigns the position returned by the method to the position variable, and the pony to the pony variable! And if you don’t care about the position, you can write:

And you will only have the pony!

One of the characteristics of JavaScript is that it allows developers to call a function with any number of arguments:

The last case is the one that is the most relevant to us. Usually, we pass fewer arguments when the parameters are optional, like in the following example:

The optional parameters usually have a default value. The OR operator will return the right operand if the left one is undefined, as will be the case if the parameter was not provided (to be completely accurate, if it is falsy, i.e 0, false, "", etc.). Using this trick, the function getPonies can then be called:

This worked alright, but it was not really obvious that the parameters were optional ones with default values, without reading the function body. ES2015 introduces a more precise way to have default parameters, directly in the function definition:

Now it is perfectly clear that the size parameter will be 10 and the page parameter will be 1 if not provided.

The default value can also be a function call:

or even other variables, either global variables, or other parameters of the function:

This mechanism for parameters can also be applied to values, for example when using a destructuring assignment:

ES2015 introduces a new syntax to define variable parameters in functions. As said in the previous part, you could always pass extra arguments to a function and get them with the special arguments variable. So you could have done something like this:

But I think we can agree that it’s neither pretty nor obvious: since the ponies parameter is never used, how do we know that we can pass several ponies?

ES2015 gives us a way better syntax, using the rest operator …​:

ponies is now a true array on which we can iterate. The for …​ of loop used for iteration is also a new feature in ES2015. It makes sure that you iterate over the collection values, and not also over its properties as for …​ in would do. Don’t you think our code is prettier and more obvious now?

The rest operator can also work when destructuring data:

The rest operator is not to be confused with the spread operator which, I’ll give you that, looks awfully similar! But the spread operator is the opposite: it takes an array and spreads it in variable arguments. The only examples I have in mind are functions like min or max, that receive variable arguments, and that you might want to call on an array:

One of the most emblematic new features, and one that we will vastly use when writing an Angular app: ES2015 introduces classes to JavaScript! You can now easily use classes and inheritance in JavaScript. You always could, using prototypal inheritance, but that was not an easy task, especially for beginners.

Now it’s very easy, take a look:

Class declarations, unlike function declarations, are not hoisted, so you need to declare a class before using it. You may have noticed the special function constructor. It is the function being called when we create a new pony, with the new operator. Here it needs a color, and we create a new Pony instance with the color set to "blue". A class can also have methods, callable on an instance, as the method toString() here.

It can also have static attributes and methods:

Static methods can be called only on the class directly:

A class can have getters and setters, if you want to hook onto these operations:

And, of course, if you have classes, you also have inheritance out of the box in ES2015.

Animal is called the base class, and Pony the derived class. As you can see, the derived class has the methods of the base class. It can also override them:

As you can see, the keyword super allows calling the method of the base class, with super.speed() for example.

The super keyword can also be used in constructors, to call the base class constructor:

Promises are not so new, and you might know them or use them already, as they were a big part of AngularJS 1.x. But since you will use them a lot in Angular, and even if you’re just using JS, I think it’s important to make a stop.

Promises aim to simplify asynchronous programming. Our JS code is full of async stuff, like AJAX requests, and usually we use callbacks to handle the result and the error. But it can get messy, with callbacks inside callbacks, and it makes the code hard to read and to maintain. Promises are much nicer than callbacks, as they flatten the code, and thus make it easier to understand. Let’s consider a simple use case, where we need to fetch a user, then their rights, then update a menu when we have these.

With callbacks:

Now, let’s compare it with promises:

I like this version, because it executes as you read it: I want to fetch a user, then get their rights, then update the menu.

As you can see, a promise is a 'thenable' object, which simply means it has a then method. This method takes two arguments: one success callback and one reject callback. The promise has three states:

When the promise is fulfilled, then the success callback is called, with the result as an argument. If the promise is rejected, then the reject callback is called, with a rejected value or an error as the argument.

So, how do you create a promise? Pretty simple, there is a new class called Promise, whose constructor expects a function with two parameters, resolve and reject.

Once you have created the promise, you can register callbacks, using the then method. This method can receive two parameters, the two callbacks you want to call in case of success or in case of failure. Here we only pass a success callback, ignoring the potential error:

Once the promise is resolved, the success callback (here simply logging the user on the console) will be called.

The cool part is that it flattens the code. For example, if your resolve callback is also returning a promise, you can write:

but more beautifully:

Another interesting thing is the error handling, as you can use one handler per promise, or one for all the chain.

One per promise:

One for the chain:

You should seriously look into Promises, because they are going to be the new way to write APIs, and every library will use them. Even the standard ones: the new Fetch API does for example.

One thing I like a lot in ES2015 is the new arrow function syntax, using the 'fat arrow' operator (⇒). It is SO useful for callbacks and anonymous functions!

Let’s take our previous example with promises:

can be written with arrow functions like this:

How cool is it? THAT cool!

Note that the return is also implicit if there is no block: no need to write user ⇒ return getRights(user). But if we did have a block, we would need the explicit return:

And it has a special trick, a great power over normal functions: the this stays lexically bounded, which means that these functions don’t have a new this as other functions do. Let’s take an example, where you are iterating over an array with the map function to find the max.

In ES5:

You would expect this to work, but it doesn’t. If you have a good eye, you may have noticed that the forEach in the find function uses this, but the this is not bound to an object. So this.max is not the max of the maxFinder object…​ Of course you can fix it easily, using an alias:

or binding the this:

or even passing it as a second parameter of the forEach function (as it was designed for):

But there is now an even more elegant solution with the arrow function syntax:

That makes the arrow functions the perfect candidates for anonymous functions in callbacks!

We were talking about promises earlier, and it’s worth knowing that another keyword was introduced to handle them more synchronously: await.

This is not a feature introduced in ECMAScript 2015 but in ECMAScript 2017, and to use await, your function must be marked as async. When you use the await keyword in front of a Promise, you pause the execution of your async function, wait for the Promise to resolve, and then resume the execution of the async function. The returned value will be the resolved value.

So we can write our previous example using async/await like this:

And your code now looks like it is synchronous! Another cool feature of async/await is that you can use a simple try/catch to handle errors:

Note that async/await is still asynchronous, although it looks like synchronous. The function execution is paused and resumed, but just like with callbacks, this doesn’t block the thread: other JavaScript events can be handled while the execution is paused.

This is a short one: you now have proper collections in ES2015. Yay \o/! We used to have dictionaries filling the role of a map, but we can now use the class Map:

We also have a class Set:

You can iterate over a collection, with the new syntax for …​ of:

You’ll see that the for …​ of syntax is the one the Angular team chose in order to iterate over a collection in a template.

Composing strings has always been painful in JavaScript, as we usually have to use concatenation:

Template literals are a new small feature, where you have to use backticks (`) instead of quotes or simple quotes, and you have a basic templating system, with multiline support:

The multiline support is especially great when your are writing HTML strings, as we will do for our Angular components:

One last feature is the ability to tag them. You can define a function, and apply it to a template string. Here askQuestion adds an interrogation point at the end of the string:

So what’s the difference with a simple function? The tag function in fact receives several arguments:

For example if we have a template string containing expressions:

then the tag function will receive the various static and dynamic parts. Here we have a tag function to uppercase the names of the protagonists:

Let’s now talk about one of the big changes introduced: modules.

A standard way to organize functions in namespaces and to dynamically load code in JS has always been lacking. Node.js has been one of the leaders in this, with a thriving ecosystem of modules using the CommonJS convention. On the browser side, there is also the AMD (Asynchronous Module Definition) API, used by RequireJS. But none of these were a real standard, thus leading to endless discussions on what’s best.

ES2015 aims to create a syntax using the best from both worlds, without caring about the actual implementation. The Ecma TC39 committee (which is responsible for evolving ES2015 and authoring the specification of the language) wanted to have a nice and easy syntax (that’s arguably CommonJS’s strong suit), but to support asynchronous loading (like AMD), and a few goodies like the possibility to statically analyze the code by tools and support cyclic dependencies nicely. The new syntax handles how you export and import things to and from modules.

This module thing is really important in Angular, as pretty much everything is defined in modules, which you have to import when you want to use them. Let’s say I want to expose a function to bet on a specific pony in a race and a function to start the race.

In races-service.js:

As you can see, this is fairly easy: the new keyword export does a straightforward job and exports the two functions.

Now, let’s say one of our application components needs to call these functions.

In another file:

That’s what is called a named export. Here we are importing the two functions, and we have to specify the filename containing these functions - here 'races-service'. Of course, you can import only one method if you need, and you can even give it an alias:

And if you want to use all the exported symbols (functions, constants, classes etc.) from the module, you can use a wildcard '*'.

As you would do with other languages, use the wildcard with care, only when you really want all the functions, or most of them. As this will be analyzed by our IDEs, we will see auto-import soon and that will free us from the bother of importing the right things.

With a wildcard, you have to use an alias, and I kind of like it, because it makes the rest of the code clearer:

If your module exposes only one function or value or class, you don’t have to use named export, and you can leverage the default keyword. It works great for classes for example:

Notice the lack of curly braces to import a default. You can import it with the alias you want, but to be consistent, it’s better to call the import with the module name (except if you have multiple modules with the same name of course, then you can choose an alias that allows you to distinguish them). And of course, you can mix default export with named ones, but obviously with only one default per module.

In Angular, you’re going to use a lot of these imports in your app. Each component and service will be a class, generally isolated in their own file and exported, and then imported when needed in other components.

That ends our gentle introduction to ES2015+. We skipped some other parts, but if you’re comfortable with this chapter, you will have no problem writing your apps in ES2015+. If you want to have a deeper understanding of this, I highly recommend Exploring JS by Axel Rauschmayer or Understanding ES6 from Nicholas C. Zakas…​ Both ebooks can be read online for free, but don’t forget to buy it to support their authors. They have done great work! Actually I’ve re-read Speaking JS, Axel’s previous book, and I again learned a few things, so if you want to refresh your JS skills, I definitely recommend it!

You may have heard that Angular apps can be written in TypeScript. And you may be wondering what TypeScript is, or what it brings to the table.

JavaScript is dynamically typed. That means you can do things like:

And it works. That’s great for all sort of things, as you can pass pretty much any object to a function and it works, as long as the object has the properties the function needs:

This dynamic nature allows wonderful things but it is also a pain for a few other reasons compared to more statically-typed languages. The most obvious might be when you call an unknown function in JS from another API, you pretty much have to read the doc (or, worse, the function code) to know what the parameter should look like. Take a look at our previous example: the method printColor needs a parameter with a color property. That can be hard to guess, and of course it is much worse in day-to-day work, where we use various libraries and services developed by fellow developers. One of Ninja Squad’s co-founders is often complaining about the lack of types in JS, and finds it regrettable he can’t be as productive and write as good code as he would in a more statically-typed environment. And he is not entirely wrong, even if he is sometimes ranting for the sake of it too! Without type information, IDEs have no real clue if you’re doing something wrong, and tools can’t help you find bugs in your code. Of course, we have tests in our apps, and Angular has always been keen on making testing easy, but it’s nearly impossible to have a perfect test coverage.

That leads to the maintainability topic. JS code can become hard to maintain, despite tests and documentation. Refactoring a huge JS app is no easy task, compared to what could be done in other statically-typed languages. Maintainability is a very important topic, and types help humans and tools to avoid mistakes when writing and maintaining code. Google has always been keen to push new solutions in that direction: it’s easy to understand as they have some of the biggest web apps of the world, with GMail, Google apps, Maps…​ So they have tried several approaches to front-end maintainability: GWT, Google Closure, Dart…​ All trying to help writing big webapps.

For Angular, the Google team wanted to help us to write better JS, by adding some type information to our code. It’s not a very new concept in JS. It was even the subject of the ECMAScript 4 specification, which was later abandoned. At first they announced AtScript, as a superset of ES2015+ with annotations (types annotations and another kind I’ll discuss later). They also announced the support of TypeScript, the Microsoft language, with additional type annotations. And then, a few months later, the TypeScript team announced that they had worked closely with the Google team, and the new version of the language (1.5) would have all the shiny new things AtScript had. And the Google team announced that AtScript was officially dropped, and that TypeScript was the new top-notch way to write Angular apps!

I think this was a smart move for several reasons. For one, no one really wants to learn another language extension. And TypeScript was already there, with an active community and ecosystem. I never really used it before Angular, but I heard good things about it, from various people. TypeScript is a Microsoft project. But it’s not the Microsoft you have in mind, from the Ballmer and Gates years. It’s the Microsoft of the Nadella era, the one opening up to its community, and, well, open-source. Google knows this, and it’s far better for them to contribute to an existing project, rather than to have to bear the burden of maintaining their own. And the TypeScript framework will gain a huge popularity boost: win-win, as your manager would say.

But the main reason to bet on TypeScript is the type system it offers. It’s an optional type system that helps without getting in the way. In fact, after coding some time with it, you’ll probably want to code every application with it. I do like what they have done, and we will have a look at what TypeScript offers in the next section. At the end, you’ll have enough understanding to read any Angular code, and you’ll be able to choose whether you want to use it or not, in your apps.

You may be wondering: why use typed code in Angular apps? Let’s take an example. Angular 1 and 2 have been built around a powerful concept named "dependency injection". You might already be familiar with it, as it is a common design pattern used in several frameworks for different languages and, as I said, already used in AngularJS 1.x.

To sum up what dependency injection is, think about a component of the app, let’s say RaceList, needing to access the races list that the service RaceService can give. You would write RaceList like this:

But it has several flaws. One of them is the testability: it is now very hard to replace the raceService by a fake (mock) one, to test our component.

If we use the Dependency Injection (DI) pattern, we delegate the creation of the RaceService to the framework, and we simply ask for an instance. The framework is now in charge of the creation of the dependency, and, well, injects it:

Now, when we test this class, we can easily pass a fake service to the constructor:

But how does the framework know what to inject in the constructor? Good question! AngularJS 1.x relied on the parameter’s names, but it had a severe limitation, because minification of your code would have changed the param name…​ You could use the array syntax to fix this, or add a metadata to the class:

We had to add some metadata for the framework to understand what classes needed to be injected with. And that’s exactly what type annotations give: a metadata giving the framework a hint it needs to do the right injection. In Angular, using TypeScript, we can write our RaceList component like:

Now the injection can be done!

That’s why we’re going to spend some time learning TypeScript (TS). Angular is clearly built to leverage this language, so we will have the easiest time writing our apps using it. And the Angular team really hopes to submit the type system to the standard committee, so maybe one day we’ll have types in JS, and all this will be usual.

Let’s dive in!

The general syntax to add type info in TypeScript is rather straightforward:

The types are easy to remember:

In such cases, the types are optional because the TS compiler can guess them (it’s called "type inference") from the values.

The type can also come from your app, as with the following class Pony:

TypeScript also supports what some languages call "generics", for example for an array:

The array can only contain ponies, and the generic notation, using <>, indicates this. You may be wondering what the point of doing this is. Adding types information will help the compiler catch possible mistakes:

So, if you need a variable to have multiple types, does it mean you’re screwed? No, because TS has a special type, called any.

It’s really useful when you don’t know the type of a value, either because it’s from a dynamic content or from a library you’re using.

If your variable can only be of type number or boolean, you can use a union type:

TypeScript also offers enum. For example, a race in our app can be either ready, started or done.

The enum is in fact a numeric value, starting at 0. You can set the value you want, though:

Since TypeScript 2.4, you can even specify a string value:

To be honest though, we don’t use enums a lot in our projects: we use union types. They are simpler and cover roughly the same use-cases:

TypeScript even allows you to create your own types, so you could do something like:

You can also set the return type of a function:

If the function returns nothing, you can show it using void:

That’s a good first step. But as I said earlier, JavaScript is great for its dynamic nature. A function will work if it receives an object with the correct property:

This function can be applied to any object with a score property. How do you translate this in TypeScript? It’s easy: you define an interface, which is like the "shape" of the object.

It means that the parameter must have a property called score of the type number. You can name these interfaces, of course:

You’ll see that we often use interfaces throughout the book to represent our entities. We use interfaces for our models in our other projects as well. We usually append a Model suffix to make it clear. It’s then very easy to create a new entity:

Another treat of JavaScript is that arguments are optional. You can omit them, and they will become undefined. But if you define a function with typed parameter in TypeScript, the compiler will shout at you if you forget them:

To show that a parameter is optional in a function (or a property in an interface), you can add ? after the parameter. Here, the points parameter could be optional:

You may also be interested in describing a parameter that must have a specific function instead of a property. The interface definition will be:

A class can implement an interface. For us, the Pony class should be able to run, so we can write:

The compiler will force us to implement a run method in the class. If we implement it badly, by expecting a string instead of a number for example, the compiler will yell:

You can also implement several interfaces if you want:

And an interface can extend one or several others:

When you’re defining a class in TypeScript, you can have properties and methods in your class. You may realize that properties in classes are not a standard ES2015+ feature. It is only possible in TypeScript.

Everything is public by default, but you can use the private keyword to hide a property or a method. If you add private or public to a constructor parameter, it is a shortcut to create and initialize a private or public member:

Which is the same as the more verbose:

These shortcuts are really useful and we’ll rely on them a lot in Angular!

When working with external libraries written in JS, you may think we are doomed because we don’t know what types of parameter the function in that library will expect. That’s one of the cool things with the TypeScript community: its members have defined interfaces for the types and functions exposed by the popular JavaScript libraries!

The files containing these interfaces have a special .d.ts extension. They contain a list of the library’s public functions. A good place to look for these files is DefinitelyTyped. For example, if you want to use TS in your AngularJS 1.x apps, you can download the proper file from the repo directly with NPM:

or download it manually. Then include the file at the top of your code, and enjoy the compilation checks:

/// <reference path="angular.d.ts" /> is a special comment recognized by TS, telling the compiler to look for the interface angular.d.ts. Now, if you misuse an AngularJS method, the compiler will complain, and you can fix it on the spot, without having to manually run your app!

Even cooler, since TypeScript 1.6, the compiler will auto-discover the type definitions of an NPM library if they are packaged with the library itself. More and more projects are adopting this approach, and so is Angular. So you don’t even have to worry about including the interfaces in your Angular project: the TS compiler will figure it out by itself if you are using NPM to manage your dependencies!

This feature was added in TypeScript 1.5, notably to help support Angular. Indeed, as we will shortly see, Angular components can be described using decorators. You may not have heard about decorators, as not every language has them. A decorator is a way to do some meta-programming. They are fairly similar to annotations which are mainly used in Java, C# and Python, and maybe other languages I don’t know. Depending on the language, you add an annotation to a method, an attribute, or a class. Generally, annotations are not really used by the language itself, but mainly by frameworks and libraries.

Decorators are really powerful: they can modify their target (method, classes, etc.), and for example alter the parameters of the call, tamper with the result, call other methods when the target is called or add metadata for a framework (which is what Angular decorators do). Until now, it was not something that was possible in JavaScript. But the language is evolving and there is now an official proposal for decorators, which may be standardized one day in the future. Note that the TypeScript implementation goes slightly further than the proposed standard.

In Angular, we will use the decorators provided by the framework. Their role is fairly basic: they add some metadata to our classes, attributes or parameters to say things like "this class is a component", "this is an optional dependency", "this is a custom property", etc. You are not required to use them, as you can add the metadata manually (if you want to stick to ES5 for example), but the code will definitely be more elegant using decorators, as provided by TypeScript.

In TypeScript, decorators start with an @, and can be applied to a class, a class property, a function or a function parameter. They can’t be applied to a constructor, but can be applied to its parameters.

To have a better grasp on this, let’s try to build a simple decorator, @Log(), that will log something every time a method is called.

It will be used like this:

To define it, we have to write a method returning a function like this:

Depending on what you want to apply your decorator to, the function will not have exactly the same arguments. Here we have a method decorator that takes 3 parameters:

Here we simply log the method name, but you could do pretty much whatever you want: interfere with the parameters, the result, calling another function, etc.

So, in our simple example, every time the getRace() or getRaces() methods are called, we’ll see a trace in the browser logs:

As a user, let’s look at what a decorator in Angular looks like:

The @Component decorator is added to the class Home. When Angular loads our app, it will find the class Home and will understand that it is a component, based on the metadata the decorator will add. Cool, huh? As you can see, a decorator can also receive parameters, here a configuration object.

I just wanted to introduce the raw concept of decorators; we’ll look into every decorator available in Angular throughout the book.

So my advice would be to give TypeScript a try! All my examples from here will be in TypeScript, as Angular and all the tooling around are really designed for it.

You can use the readonly keyword to mark the property of a class or interface as…​ read only! That way, the compiler will refuse to compile any code trying to assign a new value to the property:

The keyof keyword can be used to get a type representing the union of the names of the properties of another type. For example, you have a PonyModel interface:

You want to build a function that returns the value of a property. You could implement a naive version:

Two problems here:

This is where keyof can shine. keyof allows you to list all the keys of a type:

So we can use this type to make getProperty safer, by declaring that:

We killed two birds with one stone here:

Now let’s see how we can leverage keyof to do even more.

Let’s say you want to create a type that has exactly the same properties as PonyModel, but you want every property to be optional. You can of course define it manually:

But you can do something more generic with a mapped type:

The Partial type is a transformation that applies the ? modifier to every property of a type! In fact, you don’t have to define the type Partial yourself, because since version 2.1, it’s part of the language itself, and it’s declared exactly like in the above example.

TypeScript offers other mapped types out of the box.

Union types are really handy. Let’s say your application has authenticated users and anonymous users, and sometimes you need to do a different action depending on that. You can model this as:

I don’t know about you, but I don’t like these as …​ explicit casts. Maybe we can do better?

One possibility is to use a type guard, a special function whose sole purpose is to help the TypeScript compiler.

This is better! But we still need to return a default value, even if we covered all the possibilities.

We can slightly improve the situation if we drop the type guards and use a union type instead.

This is even better, as TypeScript automatically narrows the type in the else branch.

Sometimes you know that the model will grow in the future, and that more cases will need to be handled. For example if you introduce an AdminUser. In that case, you can use a switch. A switch statement will break if one of the cases is not handled. So introducing our AdminUser, or another type of user later, would automatically add compilation errors in every place you need to handle it!

I hope these patterns will help you. Now let’s focus on Web Components.

Components are an old fantasy in development. Something you can grab off the shelves and drop into your app, something that would work right away and bring a needed functionality to your users.

My friends, this time has come.

Well, maybe. At least, there is the start of something.

That’s not completely new. We have had components in web development for quite some time, but they usually require some kind of dependency, like jQuery, Dojo, Prototype, AngularJS, etc. Not necessarily libraries you wanted to add to your app.

Web Components attempt to solve this problem: let’s have reusable and encapsulated components.

They rely on a set of emerging standards that browsers don’t perfectly support yet. But, still, it’s an interesting topic, even if there’s a chance we’ll have to wait a few years to use them fully, or even if the concept never takes off.

This emerging standard is defined in 3 specifications:

Note that the samples are most likely to work in a recent Chrome or Firefox browser.

Custom elements are a new standard allowing developers to create their own DOM elements, making something like <ns-pony></ns-pony> a perfectly valid HTML element. The specification defines how to declare such elements, how to make them extend existing elements, how to define your API, etc.

Declaring a custom element is done using customElements.define:

And you can then use it:

Note that the name must contain a dash, so that the browser knows it is a custom element. Of course, your custom element can have properties and methods, and it also has lifecycle callbacks, to be able to execute code when the component is inserted or removed, or when one of its attributes changes. It can also have a template of its own. Maybe the ns-pony displays an image of the pony or just its name:

If you try to look at the DOM, you’ll see <ns-pony><h1>General Soda</h1></ns-pony>. But that means the CSS and JavaScript logic of your app can have undesired effects on your component. So, usually, the template is hidden and encapsulated in something called Shadow DOM, and you’ll only see <ns-pony></ns-pony> if you inspect the DOM, despite the fact that the browser displays the pony’s name.

With a mysterious name like this, you expect something with great powers. And surely it is. The Shadow DOM is a way to encapsulate the DOM of our component. This encapsulation means that the stylesheet and JavaScript logic of your app will not apply on the component and ruin it inadvertently. It gives us the perfect tool to hide the internals of a component, and be sure nothing leaks from the component to the app, or vice-versa.

Going back to our previous example:

If you try to inspect it now you should see:

Now, even if you try to add some style to the h1 elements, the visual aspect of the component won’t change at all: that’s because the Shadow DOM acts like a barrier.

Until now, we just used a string as a template of our web component. But that’s usually not the way you do that. Instead, the best practice is to use the <template> element.

A template specified in a <template> element is not displayed in your browser. Its main goal is to be cloned in an element at some point. What you declare inside will be inert: scripts don’t run, images don’t load, etc. Its content can’t be queried by the rest of the page using usual methods like getElementById() and it can be safely placed anywhere in your page.

To use a template, it needs to be cloned:

All these things put together make the Web Components. I’m far from being an expert on this topic, and there are all sorts of twisted traps on this road.

As Web Components are not fully supported by every browser, there is a polyfill you can include in your app to make sure it will work. The polyfill is called web-component.js, and it’s worth noting that it is a joint effort from Google, Mozilla and Microsoft among others.

On top of this polyfill, a few libraries have seen the light. All aim to facilitate working with Web Components, and often come with some ready-to-use Web Components.

Among the most notable initiatives, you find:

I won’t go into the details, but you can easily use an already existing component. Let’s say you want a Google Map in your app:

There are a LOT of components out there. You can have an overview on https://www.webcomponents.org/.

You can do a lot of cool things with LitElement and other similar frameworks, like two-way data binding, default values for attributes, emit custom events, react to attribute changes, repeat elements if we give a collection to a component, etc.

That’s obviously far too short a chapter to tell you everything there is to say on Web Components, but you’ll see that some of the concepts are going to pop out along your read. And you’ll definitely see that the Google team designed Angular to make it easy to use Web Components with our Angular components. It is even possible to export our own Angular components as Web Components, with the help of Angular Elements.

Pretty much all the modern JavaScript tools are built for Node.js and NPM these days. You’ll have to install Node.js and NPM on your system. The best way to do that depends on your operating system - you can find more information on the official website. Make sure you have a recent enough version of Node.js (by executing node --version).

You could setup everything by yourself, starting with a TypeScript project, then install every dependency needed, etc.

But in a real project, you’ll probably have to set up several other things too, like:

But it’s a bit cumbersome to setup everything yourself, especially when there are sooooo many tools to learn first.

These past few years, a lot of small project generators have seen the light, pretty much all using the great Yeoman. It used to be the case for AngularJS 1.x, and there were a few attempts for Angular from the community.

But this time, the Google team has been working on this issue, and they have come up with something: Angular CLI.

Angular CLI is a command line utility to easily quick start a project, already configured with Webpack as a build tool (the popular kid these years), tests, packaging, etc.

The idea is not new, and is in fact borrowed from another popular framework: EmberJS and its popularly acclaimed ember-cli.

The tool is under continuous development, with a dedicated Google team working on it and making it better and better. It is now the recommended and de facto standard way of creating and building Angular apps. So let’s give it a try, and discover the ton of cool stuff packed into it!

First let’s install Angular CLI, and generate a new application with the ng new command. If you want to use exactly the same CLI version than we are (20.0.1), you can use npm install -g @angular/cli@20.0.1 instead.

This will create a project skeleton in a new directory called ponyracer. From this directory, you can start your app with:

This will start a small HTTP server locally, with a hot reload configuration. It means that every time you modify and save a file, the server will rebuild the app, and the browser will reload it immediately.

Tada! You have your first application up and running! 🎉

Let’s dive for a few seconds into the generated code.

Open the project in your preferred IDE. You can use pretty much anything you want, but you should activate the TypeScript support for maximum comfort. Pick your favorite: Webstorm, Visual Studio Code…​ All of them have great support for TypeScript.

You should see a bunch of configuration files in the root directory: welcome to Modern JavaScript!

The first one you may recognize is the package.json file: that’s where the dependencies of the application are defined. You can have a look inside, it should now contain the following dependencies:

TypeScript itself has a configuration file tsconfig.json (and another one called tsconfig.app.json), which stores the compilation options. As we saw in the previous chapters, we are using TypeScript with decorators (hence the two options about decorators). The sourceMap option allows you to generate source maps, i.e. files that contain a mapping between the generated JavaScript code and the original TypeScript code. Those source maps are used by the browser to let you debug the JavaScript code it executes by stepping through the original TypeScript code that you have written.

TypeScript projects often also use ESLint (that we need to add to a project, as we show in the exercise Getting Started of our online course), a linter used to check your code against the best practices. ESLint has its own options, stored in .eslintrc.json, where you add/remove some of its rules.

Angular CLI itself has a configuration file angular.json if you want to override some of its defaults.

Now that we have been over the configuration, let’s see the application code.

As we saw in the previous section, a component is a combination of a view (the template) and some logic (our TS class). The CLI has already created one for us: src/app/app.ts. Let’s check it out:

Our application itself is a simple component. To tell Angular that it is a component, we use the @Component decorator. And to be able to use this decorator, we have to import it as you can see at the top of the file.

When you write new components, don’t forget to import the Component decorator. You may forget to do so at the beginning, but it won’t last, as the compiler will yell at you! ;)

You’ll see that most of the things we need are in the @angular/core module, but that’s not always the case. For example, when dealing with HTTP, we’ll use imports from @angular/common/http; or, if we use the router, we’ll import from @angular/router, etc.

The @Component decorator is expecting a configuration object. We’ll see later in detail what you can configure here, but for now let’s start with the selector property. It will tell Angular what to look for in our HTML pages. Every time Angular finds an element in our HTML which matches the selector of the component, it will create an instance of the component, and replace the content of the element by the template of the component.

So, here, every time our HTML contains an element like <ns-root />, Angular will instantiate a new instance of our App class.

A component must also have a template. We can have an inline template or externalize it in another file, like the CLI does:

The corresponding HTML is defined in app.html, with a bunch of static elements, except the first h1:

Finally, you can see that the component has an additional option: imports.

Our component is standalone (the standalone: true property is by default since Angular v19). This means that the component doesn’t need to be declared in an Angular module in order to be usable.

The property imports: [] is not always strictly required. Its goal is to tell Angular which other components, pipes and directives can be used inside the template of our component. Most of the components that we create use pipes and directives provided by Angular. These very commonly used pipes and directives are declared in an Angular module named CommonModule. Using imports: [CommonModule] in the configuration of our component thus makes it possible to use them all in its template, or you can explicitly import only the ones you need.

We were talking about ES2015+ and TS modules in the first chapters, which define imports and exports. The TypeScript compiler, when it sees an interface such as Race being used in the TypeScript source code, must know where to find the definition of this interface Race. That’s why you need to import it.

The imports property of the @Component decorator serves a similar purpose: if Angular were to find an element <ns-race> in the template of App, it would need to know where and how the corresponding Race is defined. To let it know where it can find its definition, you would need to add the Race to the imports of the App decorator.

Finally, we need to start our app, using the bootstrapApplication function. Angular CLI will by default generate a separate file containing this bootstrap logic: main.ts:

As you can see, what it expects is the root component of the application: App.

Yay! But wait a second. We need an HTML file to serve to our users, right?

The CLI created an index.html file for us, which is the single page of our application. You might wonder how it could possibly work, since it doesn’t contain any script element.

When you run ng serve, the CLI calls the TypeScript compiler. The compiler outputs JavaScript files. The CLI then bundles them and adds the necessary script elements to the index.html file (using Vite behind the scenes).

Hopefully, you now have a better understanding of the various parts of this first Angular application. It’s not really a dynamic app yet, and we could have done the same in one second in a static HTML page, I’ll give you that. So let’s jump to the next sections, and learn all about signals and templating.

A signal is a box which always contains a value. You can get the value inside the box by reading the signal. And when the signal is writable, you can put another value inside the box by setting or updating the signal. The value inside the box can be anything: a number, a string, an object, an array, or even null or undefined.

Those boxes come with super-powers. When a component template reads a signal to display its value, Angular knows that the template depends on that signal. And thus, every time you update that signal with a new value, Angular knows that it must update the DOM generated by this template.

This is the principle of the new change detection mechanism used by Angular. If all components use signals to store the data displayed by their template, then the brute-force mechanism is not necessary anymore.

This revolution that started in Angular 16 has not ended yet. But all the signal-related features that were introduced since then are now stable enough. We can use them in our applications.

This book will thus describe how to use Angular in the new, modern way, based on signals. We will mention how it was done before though, because there’s a good chance that you’ll find code in your applications that still uses the legacy way of writing components. Both ways can coexist in the same application, but we advise you to start adopting the newest best practices.

Let’s now start by showing how you can create a writable signal, read its value, and update it. We’ll talk about the other kinds of signals and about their other capabilities in later chapters of the book, when we will need them.

To create a writable signal, call the signal() function (from @angular/core) with the value that it must contain initially. All the following examples create instances of WritableSignal which, as you can see, is a generic type specifying the type of the value contained in the signal.

A signal is both an object and a function. To get the value contained in the signal, you call the signal.

To change the value of the signal (and thus notify Angular that this signal has a new value), you call its set() method:

Now let’s say you only want to change the color of Rainbow Dash. You might be tempted to read the value of the signal and then mutate it. Or even to mutate it and then set it back into the signal again. That’s something you should never do :

If you mutate the object contained in a signal, or if you set a signal with the same object it already contains, then Angular will consider that the value has not changed, which will lead to bugs.

Instead, treat the value as immutable, and replace the old value with a new one. The update() method, along with the destructuring operator, can be used to create a new value from the existing one:

But it’s just a different way of doing:

Let’s now see how we can display the state of our components in a template!

Interpolation is a big word for a simple concept.

Quick example:

We have an App component that will be activated every time Angular finds a <ns-root> tag. The App class has a property, numberOfUsers. And the template has been augmented with an <h2> tag, using the famous double curly braces (a.k.a. "mustaches") to indicate that an expression has to be evaluated. This kind of templating is called interpolation.

We should now see in the browser:

as {{ numberOfUsers }} will be replaced by its value. When Angular detects a <ns-root> element in the page, it creates an instance of the App class, and this instance is the evaluation context of the template’s expressions. Here the App instance sets the numberOfUsers property to '146', so we have '146' displayed on screen.

The magic is that, whenever the value of numberOfUsers changes in our object, the page will be automatically updated! Or rather, that’s how it works now, with the "brute-force" change detection mechanism that Angular currently uses. But we’ve seen in the previous chapter that Angular now promotes using signals to help it detect changes in a more clinical way. If we wanted the number of users to change over time, we should thus store it in a signal, and call the signal in the template:

One important fact to remember: if we try to display a variable that is not initialized, then, instead of displaying undefined, Angular is going to display an empty string. The same will happen for a null value.

Let’s say that, instead of a simple value, our first component has a more complex user object, reflecting the current user.

As you can see, we can interpolate more complex expressions, like accessing the property of an object.

What happens if we have a typo in our template, with a property that does not exist in the class?

When compiling the app, you will have an error, telling you that this property does not exist:

That’s great, because now you are quite sure that your templates are correct.

One last little but handy feature. What happens if my user object is in fact fetched from the server, and thus initialized to undefined before being valued with the result of the server call? Is there a way to avoid the errors when the template is compiled?

Yes, there is: instead of writing user().name, you write user()?.name:

And you don’t have errors anymore! The ?. is called the "optional chaining operator". It was usable in Angular expressions even before being introduced in standard JavaScript and TypeScript.

Let’s go back to our example. We are now displaying a greeting message. Maybe we can go a step further and display the upcoming pony races.

That should lead us to write our second component. For now, we’ll just make it simple:

Nothing fancy: a simple class, decorated with @Component to give it a selector to match and an inline template.

Now we want to include this component in our App template. What do we need to do?

We have our app component, App, where we want to display the pony races component, Races.

As you can see, we added the Races component in the template, by including a tag whose name matches the selector we defined for the component.

Buuuuuut, that will not work: your browser will not display the races component.

Why is that? Angular doesn’t know about this Races yet.

The fix is simple: you need to add Races to the imports of the App decorator. That way, when Angular compiles the template of App, it will look for a component with the ns-races selector in the list of imported components, and will thus know that it must instantiate and display the Races.

Note that you will pass the class directly, so you’ll have to import it. And in order to be able import it, you need to export the class Races in its source file races.ts (read the section about ES2015 modules again if that’s not clear for you). So Races will look like:

Now, our races component will proudly be displayed in our browser:

Interpolation is only one of the ways to have dynamic parts in your template.

In fact, the interpolation we just saw is just an easy way to use what is the core of Angular templating system: property binding.

In Angular, every DOM property can be written to via special attributes on HTML elements surrounded with square brackets []. It looks weird at first, but in fact it is valid HTML (it surprised me too). An HTML attribute can start with pretty much anything you want except a few characters like quotes, apostrophes, slashes, equals, spaces…​

I’m talking about DOM properties, but maybe this is not clear for you. We usually write to HTML attributes, right? Right, usually we do. Let’s take this simple HTML:

The input tag above has two attributes: a type attribute and a value attribute. When the browser parses this tag, it creates a corresponding DOM node (an HTMLInputElement if we want to be accurate), which has the matching properties type and value. Each standard HTML attribute has a corresponding property in the DOM node. But the DOM node also has additional properties, which don’t have a corresponding attribute. For example: childElementCount, innerHTML or textContent.

The interpolation we had above to display the user’s name:

is just sugar syntax for the following:

The square bracket syntax allows you to modify the DOM property textContent, and we give it the value user.name which will be evaluated in the context of the current component instance, as it was for the interpolation.

Note that the parser is case-sensitive, so you have to write the property name with the correct case: textcontent or TEXTCONTENT will not work. It has to be textContent.

DOM properties have a great advantage over HTML attributes: they have up-to-date values. In my input example, the value attribute will always contain 'hello', whereas the value property of the DOM node is dynamically modified by the browser, and thus contains whatever the user has entered in the text field.

Finally, properties can have boolean values, whereas some attributes can only reflect it by being present or absent on the start tag. For example, you have the selected attribute on the <option> tag: no matter what value you give it, it will select the option, as long as it is present.

With properties access like Angular gives us, you can write:

And the pony will be selected if isPonySelected returns true, and will not be selected if it returns false. And whenever the value of isPonySelected changes, the selected property will be updated.

You can also access nested properties like the color attribute of the style property.

If the foreground signal is changing to 'green', then the text will update its color to 'green' too!

So Angular is using properties. Which values can we pass? We already saw the interpolation property="{{ expression }}":

is the same as [property]="expression" (which you will usually prefer):

If you want to write 'Pony' followed by the pony’s name, you have two options:

If your value is not a dynamic one, you can simply write property="value":

All of these are equivalent. You need to remember that if an HTML attribute is not surrounded by square brackets (name="…​"), then the value is a string. Whereas if it’s surrounded by square brackets ([name]="…​"), then the value is an expression, evaluated by Angular.

If you’re developing a webapp, you know that displaying things is just one part of the job: you also have to deal with user interactions. To allow this, the browser fires events, which you can listen to: click, keyup, mousemove, etc.

Going back to our Races, we now want to have a button that will display the races when clicked.

Reacting to an event can be done as follows:

A click on the button of the example above will trigger a call to the component method onButtonClick().

Let’s add this to our component:

If you try this in your browser, you should initially see "0 races". And after your click, "0 races" should become "2 races". Yay \o/

The statement can be a function call, but it can be any executable statement, or even a sequence of executable statements, like:

However I would not advise you to do this. Using methods is a better way of encapsulating the behavior: it makes your code easier to maintain and test, and it makes the view simpler.

The cool thing is that it works with standard DOM events, but also with custom events that might fire from your Angular components or from web components. We’ll see later how to fire custom events.

For the moment, let’s say the Races component emits a custom event to notify the app that a new race is available.

Our template in the App component would then look like:

We can easily figure out that the <ns-races> component has a custom event newRaceAvailable and that, when this event is fired, the method onNewRace() of our App is called.

Angular will listen for the event on the element and on its children, so it will react to events that bubble. Consider the template:

Even though the user clicks on the button embedded inside the div, the onButtonClick() method will be called, because the event bubbles up.

Oh, and you can access the event in the method called! You just have to pass $event to your method:

Then you can handle the event in your component class:

By default, the event will continue to bubble up, eventually triggering other event listeners up in the hierarchy.

You can use the event to prevent the default behavior and/or cancel propagation if you want:

One cool feature is that you can also easily handle keyboard events with:

Every time you will press the space key, the onSpacePress() method will be called. And you can do a crazy combo, like (keydown.alt.space), etc.

To conclude this part, I want to point out that there is a big difference between something like:

and

In the first case, with property binding, the doSomething() value is called an expression, and will be evaluated at each change detection cycle to see if the property needs to be updated.

In the second case, however, with event binding, the doSomething() value is called a statement, and will be evaluated only when the event is triggered.

By definition they have completely different goals and, as you might suspect, they have different restrictions.

Expressions and statements differ in several ways.

An expression will be executed many times, as part of the change detection. It should thus be as fast as possible. Basically, an Angular expression is a simplified version of an expression you could write in JavaScript.

If you are using user.name as an expression, user should be defined, otherwise Angular will throw an error.

An expression must be single: you can’t chain several ones separated with a semi-colon.

An expression should not have any side effect. That means it can’t be an assignment, for example.

It cannot contain keywords, like if, var, etc.

A statement, on the other hand, is triggered on the matching event. If you try to use a statement like race.show() where race is undefined, you will have an error. You can chain several statements, separated with a semicolon. A statement can, and generally should, have side effects. That’s the point of reacting to an event: to make something happen. A statement can be a variable assignment, and can contain keywords.

When I say that Angular will look in the component instance to find a variable, it is not technically correct. In fact, it will check the component instance and the local variables. Local variables are variables that you can dynamically declare in your template using the # syntax.

Let’s say you want to display the value of an input:

Using the # syntax, we are creating a local variable name referencing the DOM object HTMLInputElement. This local variable can be used anywhere in the template. As it has a value property, we can display this property in an interpolated expression. I’ll come back to this example later.

Another useful usage of local variables is when you want to execute some kind of action on another element.

For example, you may want to give the focus on an element when you click on a button. This was a bit cumbersome in AngularJS 1.x, as you had to create a custom directive and so on.

The focus() method is a standard part of the DOM API, and we can leverage this. Using a local variable, it’s a no-brainer in Angular:

It can also be used with a custom component - one we created in our app, imported from another project, or even with a real Web Component:

Here, the button can start playing the video of the <google-youtube> component. This is actually a real Web Component written with Polymer! This component has a play() method that Angular will call when you click on the button, which is pretty cool!

Local variables have a few use cases, and we will gradually see them.

Now, our Races is still not displaying the races :) The "proper way" in Angular would mean creating another component Race to display each race. We are going to do something slightly simpler, and just write a simple <ul><li> list.

Property and event binding is great, but it does not let us change the DOM structure, like iterating over a collection and adding an element per item. To do so, we can use special instructions in the template, that have been introduced in Angular v18, under the name Built-in control flow.

Previously, we needed to use special directives, that are called structural directives, like ngIf, ngFor, ngSwitch to handle these cases. A directive in Angular is really close to a component, but does not have a template. It is used to add behavior to an element. Structural directives are a subset of directives that can change the structure of the DOM. They still exist, so you can still use ngIf, ngFor, ngSwitch, etc. in your templates, but they are deprecated and the recommended way is to use the new control flow syntax. If you’re interested in the old way, you can read the chapter about structural directives later in this book.

Let’s see how we can use the control flow syntax.

Angular v18.1 added a new feature to the template syntax: template variables. It is now possible to define a variable in the template, using the @let instruction, without having to declare it in the component class.

The syntax is simple: @let variableName = expression;. Let’s say our component has a count field defined in its class, then we can define a variable in the template like this:

This can be handy when you want to use a value in several places in your template, especially if it is a complex expression. Sometimes you can create a dedicated field in the component class, but sometimes you can’t, for example in a for loop:

This can be written more cleanly using @let:

The structural directives provided by Angular rely on using a ng-template element, inspired by the template standard tag of the HTML specification.

Here we have defined a template, displaying a simple div. Alone, it does not have much use, as the browser will not display it. But if we add one 'template' element in a view, then Angular can use its content. The structural directives have the ability to do simple actions with this content, like displaying it or not, repeating it, etc.

Let’s see which directives are available!

Angular comes with plenty of other useful directives, but which are not structural. We’ll use several of them when writing forms, for example. Two of them are commonly used to act on the CSS styles of the elements.

The Angular templating system gives us a powerful syntax to express the dynamic part of our HTML. It allows to express data and property binding, event binding and templating concerns, in a clear way, each with their own symbols:

It takes some time to be fluent in this syntax, but you will soon be up to speed, and then it’s easy to read and write.

Let’s go through a complete example before moving on.

I want to write a Ponies component, displaying a list of ponies. Each pony should be represented by a Pony component, but we haven’t seen yet how to pass parameters to a component. So, for now, we are going to display a simple list. The list should be displayed only if it’s not empty, and I’d like to have some color for the even lines of my list. Finally, I want to be able to refresh the list with a button click.

Ready?

We start to write our component, in its own file:

You can add it to the App component we wrote in the previous chapter to test it. You will have to import it and insert the tag <ns-ponies /> in the template.

Our new component has a list of ponies wrapped in a signal:

We are going to display this list, using @for:

One thing is missing, the refresh button:

And of course, a touch of color to finish, with the use of [style.color] and the $even variable:

As you can see, we have used all the range of the templating syntax, and we have a perfectly working component.

So far, we have seen some small components. And of course, you can sense that, as they are the backbone of our apps, they can be more complex than what we have seen. How do we pass data? How do we manage the lifecycle of our component? What are the best practices to build these things?

Directives: What do they do? Let’s find out!

A directive is very much like a component, except it does not have a template. The goal of a component is to enrich HTML by using custom HTML elements like <ns-pony /> to display a pony. Directives also enrich HTML by letting you attach a custom behavior to existing HTML elements. For example, you could attach a drag directive to a <div>, or a <section>, or even a <ns-pony> element to make it draggable.

We’ve already seen the ngClass directive: it allows adding or removing CSS classes to HTML elements. You can attach several directives to the same element. For example, a <div> could need CSS classes added to them by ngClass, and could also be made draggable by the drag directive.

The way we define directives is similar to the way we define components. We create a class. We decorate this class with a @Directive decorator. And we pass metadata to this decorator as we did for the @Component decorator. In fact, components are directives. All the metadata that we specify on a directive, we can also pass them to a component. Their lifecycles are also pretty much identical.

Even though directives are a big part of what makes Angular extremely powerful, they’re more commonly used in low-level, foundational parts of libraries, or of the framework itself. A typical web application developer rarely creates directives, and more commonly creates components.

Let’s learn about the most common things we can define on components and directives. More advanced stuff will be described later.

The selector is what allows Angular to identify a component or directive inside HTML templates.

Selectors can be of various types:

For example, this is a very simple directive that does nothing but gets activated if the attribute doNothing is on an element:

Such a directive will be activated in a component like this Test:

A more complex selector could be:

Here it will match all div elements with a loggable class and a logText attribute that don’t have an attribute notLoggable with a true value.

So this template will trigger the directive:

But this one will not:

Let’s be honest, though: if you are writing something like this, there is something wrong! 😊

Inputs are what allows a component or directive to receive information from its parent component. You can see them as parameters of a function: the calling function uses parameters to pass data to the called function.

To pass an input to a component or directive, we use the property binding syntax that we described in the previous chapter. For example, if we wanted to pass a color to the pony component, we would use:

to pass the literal 'blue' string, or:

to pass the value of the Angular expression selectedColor().

In order for a directive or component to accept information from its parent, it must define inputs.

Here’s how the pony component can receive a color from its parent component:

The color property is a special kind of signal: an InputSignal. Such a signal is not writable. The Pony can’t change its color. The only way to change its value is to bind another value from the parent component.

The input in the above example is optional. That means that the parent component is allowed to not pass a color to the component <ns-pony />. But the input is typed, so if it passes a value, the value must be a string. If the parent doesn’t pass any color, the color signal will contain undefined. The type of color is InputSignal<string | undefined>.

The component could choose to use a default value for the color, in case the parent doesn’t pass any. The type of color would then be InputSignal<string>: it always has a string value.

Or it could choose to force the parent to pass a value by making the input required. In this case, the parent component template would fail to compile if it didn’t pass a value.

If you wanted to use color as the property name, but prefer to use another name in the templates for the input, you can choose to give it an alias.

For example, if the input is defined that way:

then the parent will use c to pass a color value:

The above examples all define an input of type string. But anything can be passed as input. It’s very common to pass complex objects as inputs, such as a PonyModel object that would contain a name, a color, a birthdate, etc.

We’ve just seen how to define inputs as signals. That’s the modern way of doing it. If you work on an existing code base, the inputs of your components are probably defined the old way, using the @Input decorator.

Inputs defined this way are passed by the parent component using the exact same property binding syntax. The difference is only in the component which defines the input. Such "legacy" inputs are simple properties (not signals), decorated with @Input(). Here are the above examples rewritten in the legacy way.

An optional input:

An optional input with a default value:

A required input:

A required input with an alias:

OK, now what about passing data up? We can’t use properties to pass data from Pony to Ponies. But we can use events!

Let’s go back to our latest example, and say we want to be able to select a pony by clicking on it and inform the parent component. For this, we will use a custom event.

This is important. In Angular, data flows into a component via properties, and flows out of a component via events.

Custom events are emitted using an OutputEmitterRef. You don’t really need to use this awful type name. Such objects are created for you by the output() function.

You’re free to choose the type of the events that you emit. It could be undefined, to just signal that something happened. Or it could be a PonyModel, to pass all the information about the pony that has just been selected, for example.

Let’s say we want to emit an event called ponySelected. We have two things to do:

To use it in the template of the parent component:

In the above example, every time the user clicks on the button in the pony component, it emits an event ponySelected, with the pony as a value (the parameter of the emit() method). The parent component is listening to this event, as you can see in the template, and will call its betOnPony method with the value of the event $event. $event is the syntax you have to use to access the emitted event. Here, it is the PonyModel object.

The parent component must then have a method betOnPony(), which will be called with the selected pony:

As for the inputs, if you wish, you can choose an alias for the output:

The parent component will then have to use this alias to listen to the event:

Even though outputs have nothing to do with signals, the output() function described above was introduced at the same time as the input() function, to have a pleasant symmetry between inputs and outputs.

Before that, outputs were defined using the @Output decorator. And they were also using a different class: EventEmitter which was unnecessarily tied to the RxJS library (we’ll talk about this library in a few chapters). In case your codebase still uses them, here’s how an output is defined in the legacy way:

and here’s how an alias can be specified for the input:

Components and directives have a lifecycle. When Angular must display a component, it starts by constructing it and thus calls the component class constructor. Then it will pass the initial input values to the component. If the expressions passed as inputs later have different values, then these new values are written to the inputs again. And finally, if the user navigates away from this component, for example, the component is destroyed. Hopefully, the component isn’t reachable from anywhere anymore at this point, and the JavaScript virtual machine can garbage collect the component object.

Angular allows you to react to those various phases (and other ones, more advanced, that we’ll discover later). One thing is very important to understand: inputs are passed after the component has been constructed. It’s thus forbidden to read inputs while the component is being constructed.

With the signal inputs, trying to do that will lead to an exception being thrown by the InputSignal. With the legacy inputs, trying to do that will just give you the default value of the property, rather than the one actually bound by the parent component.

That means that the following component will not work:

If you want to access the value of an input, to load additional data from the server, for example, you can use a lifecycle hook. More powerful options are available for signal inputs, which we’ll discover in the next chapter.

Several hooks are available:

Other phases are available but are for more advanced use cases. We will describe them in the Advanced components and directives chapter a bit further.

Our previous example will work better using ngOnInit. Angular invokes the method ngOnInit() if it’s present, so you just have to implement it in your directive/component. But the best practice is to implement the OnInit interface. That forces you to implement the method, and make sure you have defined it correctly:

Now we have access to our inputs!

If you want to do something every time an input changes, use ngOnChanges:

The changes parameter is a record, with the input names as keys, and a SimpleChange object with two attributes (the previous and the current value) as value, as well as a method isFirstChange() to know if it is…​ the first change.

The ngOnDestroy phase is designed to clean the component – for example, to cancel background tasks. Here, the Pony is logging "hello" every second when it is created. When the component is removed from the page, you want to stop the setInterval to avoid a memory leak:

If you don’t do this, JavaScript will keep the instance of the component in memory, and it will log every second forever.

Inputs, outputs, and the hooks we’ve just described are common to directives and components. Components, however, can define styles that will apply to their template, and must have an associated template.

The main feature of a @Component is to have a template, whereas a directive does not have one. You can either declare your template inline, using template or use a URL to put it in a separate file with templateUrl (but you can’t do both at the same time).

As a rule of thumb, if your template is small (1-2 lines), it’s perfectly fine to keep it inline. When it starts to grow, move it to its own file to avoid cluttering your component.

You can also specify the styles of your component. It is particularly useful if you plan to have really isolated components. You can specify this using styles or styleUrl (or styleUrls if you have several files).

As you can see below, the styles attribute takes an array of CSS rules as a string. You can imagine it grows pretty quickly, so using a separate file and styleUrl is a good idea. As the name of the latter suggests, you can specify an array of URLs.

Have you ever used a spreadsheet with formulas? It’s great, isn’t it? You can sum all the amounts of a sales column and store the result in a total cell. Then you can use another formula to apply the VAT to that total and store the result in yet another cell. If you add a sale, or if you change an amount, the total is automatically recomputed, and the VAT total as well. Computed signals allow doing the same thing.

Let’s say our pony component receives a PonyModel as input, containing (among other properties) a name and a color. And let’s say its template wants to display its identity as NAME (color) (for example "RAINBOW DASH (blue)").

The first thing that comes to mind is to do it this way in the template:

This is absolutely fine. But if the application uses the "brute-force" change detection, this transformation will be done many times, even if the pony is the same as before. And if the template must display the identity several times, copy and pasting this is not the best idea.

We might improve that by delegating to a method in the component:

This avoids the duplication, but it still invokes the identity() method many times unnecessarily.

A better way would be to use ngOnChanges to compute the identity when the ponyModel changes, and store the result in another property:

That is nice. But if we later introduce another input, we’ll recompute the identity whenever this unrelated input changes, unless we make our ngOnChanges method more complex. Also, note how we’re forced to initialize the identity signal with a fake default value. There got to be an even better way.

The better way is to use a computed signal. A computed signal is a read-only signal, whose value is derived from another (or several other) signal(s):

The identity property is now a Signal<string>, whose value will always contain the identity of the pony contained in the ponyModel signal. There is a dependency that is created and tracked by Angular between the two signals. Whenever ponyModel changes, identity also changes.

Computed signals are memoized and lazy, which make them perfect for representing state that can be read many times. This means that the identity of a pony is stored inside the computed signal. And it’s not recomputed every time we write a new pony, but only the next time the identity signal is read. You can try to execute the following example, and see what is being logged:

The output will be:

Computed signals are even greater when they depend on multiple signals. Let’s say you have a form letting you enter a price and a quantity, and displaying a total, as well as a vat-included total. Programming that imperatively requires you to think about computing the total and the vat-included total whenever you change the price, and also whenever you change the quantity. Dependencies are not so obvious, and it can quickly become spaghetti code. Including yet another rule (like a discount percentage) could easily introduce a bug. Once the form input values are available as signals, computed signals make the logic very easy to implement, and very efficient as well:

Effects are another way to react to signal changes. Instead of being used to compute a derived value, they’re used to trigger a side effect (hence the name) when a signal changes. Examples of such a side effect are storing a value of a signal in local storage when a signal changes, or updating the DOM when a signal changes. It might be tempting to use an effect to update other signals when a source signal changes. That’s possible, but it can lead to infinite loops, and computed signals are more suited to such a task.

To illustrate how effects work, we will just use one that logs to the console.

This example will log the name and color of the pony every time the parent passes a pony as input.

Unlike computed signals, effects are bound to the component (or directive, or service, or pipe) in which they are constructed. An effect must be created while the component is being constructed. It’s possible to do it elsewhere, but it’s more complex, and we will learn about that later. The advantage of this restriction is that Angular takes care of destroying the effect when its owning component is destroyed.

Another feature that must be understood is that effects are not executed synchronously, whenever one of their source signals change. Instead, they’re called asynchronously, before the change detection. This means that intermediate signal values won’t be noticed by effects.

Let’s illustrate this using the following component:

Creating the component will log "The score is now 0", because the effect function is always executed once initially to be able to know which signals the effect depends on.

Calling the plusTwo() method (as a reaction to a button click for example), will set the score signal to 1, then to 2. But only the final value of the score (i.e. the value that is stored in the signal after the click event has been handled), will be logged by the effect. So the console will only log "The score is now 2".

There are still more things to learn about signals, computed and effect (such as the untracked function and the equality function, effect cleaning functions), but we will keep that for later.

You now know enough to start using signals. And hopefully, you understand why they are so great in helping us to manage the state of our components in a simple, expressive and concise way.

If you use the ShadowDom option, you’re telling Angular to use the Shadow DOM of your browser to take care of the encapsulation. The Shadow DOM is a part of the Web Component specification. This specification allows you to create elements in a special DOM, which is perfectly encapsulated. With this strategy, if we look at the generated DOM with our browser’s inspector, we’ll see:

You can spot the #shadow-root (open) that Chrome will display in the inspector: that’s because our component has been included in a Shadow DOM element! And we can also see that the style was added at the top of our component’s content.

With the ShadowDom strategy, you are sure that your component’s styles are not "bleeding" into your child components if they are using the ShadowDom strategy as well. But they will bleed into the child components if they don’t, which can be useful in some cases.

But remember, Shadow DOM is a rather new specification, so it’s not available in every browser. You can check the availability on the awesome website caniuse.com. So be careful when you use it in your apps!

As a side note: the component selector must be hyphenated otherwise the ShadowDOM strategy won’t work.

As said earlier, this is the default strategy. And the reason is really simple: it emulates (hence the name) the ShadowDom strategy, but without using the Shadow DOM. It’s safe to use everywhere and styles won’t bleed into child components.

To achieve that, Angular will take the CSS defined for the component, and inline it inside the <head> element of the page (and not in each component as we saw for the ShadowDom strategy). But before inlining it, it’s going to rewrite the CSS selector, to append a unique attribute identifier. This unique attribute is then added to all the elements of our component’s template! That way the style will only apply to our component. The same example, would now give:

The red class selector has been rewritten to .red[_ngcontent-dvb-3], so it will only apply on elements that have both the class red and the attribute _ngcontent-dvb-3. You can see that this attribute has also been added to our div automatically, so that works perfectly. The <ns-pony> element also has a few attributes: _ngcontent-dvb-2 which is the unique identifier generated for its parent, and _nghost-dvb-3 which is a unique identifier for the host element itself. Yes, we can also add styles that apply on the host element, as we’ll see shortly.

This strategy is not doing any encapsulation. The styles will be inlined at the top of the page (as for the Emulated strategy), but not rewritten. They then behave like "normal" styles, cascading into children.

A special CSS selector exists to style only the host element. It is called :host, and it comes from the Web Component specification:

It will be kept as is for the ShadowDom strategy and rewritten into [_nghost-xxx] if you use Emulated.

To conclude, you don’t have to do much to have perfectly encapsulated styles, because the Emulated strategy takes care of this business for us. You can switch the strategy to use the ShadowDom one if you target only specific browsers, or None if you don’t want to encapsulate styles. This strategy can be tweaked per component, or globally for your whole app in the root module.

Sometimes the raw data is not what we want to display in the view. We often want to transform it, format it, etc. AngularJS 1.x had a very handy feature to do this, very badly named 'filters'. Lessons have been learned and now these data transformers have a meaningful name! Nah, I’m just kidding, they are called 'pipes' :).

Similarly as components, pipes can be standalone or not. The pipes that are provided by Angular and that we will discuss here are all standalone, and are all part of CommonModule. So, to use them in your components, you’ll have to add them, or the whole CommonModule, to their imports.

Let’s take an example and see how we can use pipes.

A pipe that is not really useful in a production app, but very handy when you are debugging your app, is JsonPipe. Basically, this pipe applies JSON.stringify() to your data. If you have some data in your component, a signal containing an array of ponies called ponies, for example, and you want to quickly see what’s inside, you may want to try something like:

Tough luck, it’s going to display [object Object]…​

But JsonPipe is here to rescue us. You can use it in your HTML, in any expression:

And it will display the JSON representation of your object:

You can see where the name 'pipe' is coming from. To use a pipe, you have to add a pipe (|) character after your data, and then the name of the pipe you want to use. The expression is evaluated and the result goes through the pipe. It’s possible to chain several pipes, one after another, like:

We’ll come back to the slice pipe, but you can see that we are chaining the slice pipe and then the json one.

You can use it in an interpolation expression or in a property expression, but not in an event statement.

If you want to display just a part of a list, slice is your friend. It works like the slice method in JavaScript, and takes two arguments: a start index and, optionally, an end index.

To pass an argument to a pipe, you have to add a colon :, then the first argument, then possibly, another colon and the second argument etc.

This example will display the first two elements of my list of ponies.

slice works with arrays and strings, so you can also truncate a string:

and that will display only 'Ninja'.

You can give the slice pipe only one index n, and it will take the elements from n to the end.

If you give it a negative integer, it will take the n last elements.

As we saw, you can also give the pipe an end index: it will take the elements until this index. If this index is negative, it will take the elements until the index, but starting from the end.

As you can use slice in any expression, you can use it even with a @for:

The component will create only two div elements here, for the first two ponies, as we have applied the slice pipe to the collection.

The pipe argument can of course be a dynamic value:

You can use this to create a dynamic display where your user chooses how many elements she/he wants to see.

This pipe, introduced in Angular 6.1, allows you to iterate over a Map or an object, and to display the keys/values in our templates.

Note that it orders the keys:

And if the keys have different types, they will be cast to strings and then compared.

If you have null or undefined keys, they will be displayed at the end.

It’s also possible to define your own comparator function:

As its name makes it clear enough, this pipe transforms a string into its uppercase version:

The counterpart of the previous one, this pipe transforms a string into its lowercase version:

Angular 4 introduced a new titlecase pipe. It capitalizes the first letter of all words:

This pipe lets you format a number.

It takes one parameter, a string, formatted as {integerDigits}.{minFractionDigits}-{maxFractionDigits}, but every part is optional. Each part indicates:

A few examples, starting with what we have with no pipe:

Using the number pipe will group the integer part, even with no digits required:

The integerDigits parameter will left-pad the integer part with zeros if needed:

The minFractionDigits is the minimum size of the decimal part, so it will pad zeros on the right until reached:

The maxFractionDigits is the maximum size of the decimal part. You have to specify a minFractionDigits, even at 0, if you want to use it. If the number has more decimals than that, then it is rounded:

Based on the same principle as number, percent lets you display…​ a percentage!

As you can imagine, this pipe lets you format an amount of money in the currency you want. You have to give it at least one parameter:

If you don’t provide the ISO string representing the currency, then USD is used, unless you configure it globally (since Angular 9). Check the Internationalization chapter if you want to learn how.

This pipe is way more powerful than what you might expect: it relies on the ISO 4217 specification to determine the number of digits in the decimal part. For example, formatting an amount in Chilean pesos results in an amount with no digits (as pesos don’t have cents), whereas formatting an amount in Tunisian dinars results in an amount with 3 digits (as it has millimes).

The date pipe formats a date value to a string of the desired format. The date can be a Date object or a number of milliseconds. The format specified can be either a pattern like 'dd/MM/yyyy', 'MM-yy' or one of the predefined symbolic names available like 'short', 'longDate', etc.:

Of course, you can also display the time portion of the date:

The async pipe allows data obtained asynchronously to be displayed. It can handle async data that comes from a Promise or an Observable. I hope you now know what a Promise is (otherwise go back to the ES2015+ chapter), and we’ll come back to Observables quickly.

The async pipe returns null until the data is finally available (i.e. until the promise is resolved, in case of a promise). Once resolved, the resolved value is returned. More importantly, it triggers a change detection check once the data is available.

The following example uses a Promise:

You can see the async pipe is applied to the variable asyncGreeting. This one is a promise, resolved after 1 second. Once the promise is resolved, our browser will display:

Even more interesting, if the source is an Observable, then the pipe will do the unsubscribe part itself when the pipe is destroyed (for example when the user navigates to another component, or because it’s part of an ngIf that becomes false).

And to avoid multiple subscriptions to your Observable or calling your promise multiple times, you can store the result of the call with as:

If you want to learn more about this pipe, check the Performances chapter near the end of this ebook.

It is also possible to use the formatting functions offered by the framework directly. For example, to format a number, we can use the formatNumber function:

Of course, you can also create your own pipes. That’s sometimes very useful. In AngularJS 1.x, we often used custom filters. For example, we built one to display how much time elapsed since an action the user did (like 12 seconds ago or 3 days ago) in several of our apps. Let’s see how we would do this in Angular!

First we need to create a new class. It should implement the PipeTransform interface, which forces us to have a transform() method, the one doing the heavy lifting.

Does not sound too hard. Let’s give it a try!

We are going to use the parseISO function from date-fns to parse the date, and the formatDistanceToNow function to display how much time has elapsed since the date.

You can install date-fns using NPM if you want:

The types for date-fns are already included in the NPM dependency, so the TypeScript compiler should be happy without us doing anything.

Now, we need to tell Angular that this class is a pipe. For this, there is a special decorator we can use: @Pipe.

The chosen name will be the one allowing to use the pipe in the template.

To use the pipe in a template, the last thing you need to do is to add the pipe to the imports of the component using it.

Dependency injection is a well-known design pattern. Let’s take a component of our application. This component may need some features offered by other parts of our app (let’s say a service). That’s what we call a dependency. Instead of letting the component create its dependencies, the idea is to let the framework create them, and provide them to the component. That is known as "inversion of control".

It has several interesting advantages:

It’s a concept vastly used on the server side, but not so much on the frontend side, except in Angular.

To be able to use dependency injection, we need a few things:

The framework does the rest of the job. When we ask for a dependency in a component, it will look into the registry if it can find it, will get the instance of the dependency or create one, and finally inject it in our component.

A dependency can be a service provided by Angular, or a service we have written ourselves.

Let’s take an example with a LoggingService service. In development, we want to log to the browser’s console. In production, we want to aggregate logs on a remote server. Let’s start by the development version.

It’s easy to inject that dependency in a component or a service. We just have to use the type system and the inject function of Angular.

Let’s say we want to write a RaceService that would use the LoggingService:

The ìnject function tells Angular to fetch the LoggingService service and returns it.

In fact, inject is a relatively new way of injecting dependencies. Before it was introduced in Angular 14, the only way to inject a dependency was to declare the dependency as an argument of the constructor. So we could also write our RaceService this way:

Constructor injection is still very much supported, but inject is now generally seen as a preferred option, and has opened the door to interesting API improvements.

Now, we can add a method list() to our service, which will call our backend and log a trace using the LoggingService service:

In Angular, all services must be decorated with @Injectable():

As we are using the LoggingService, we need to "register" it, to make it available for injection.

The easiest (and recommended) way to do this is to add the @Injectable decorator on LoggingService and use providedIn directly inside:

Another way to do this is to use the providers option of bootstrapApplication() function we saw earlier:

Now, if we want to make our RaceService available for injection in other services or components, we have to register it too:

And we’re done!

We can use our new service wherever we want. Let’s test it in the App component:

As we want to use an API to log our traces in production, we need to provide a different implementation of the LoggingService service.

I’ll come back to the testability advantages brought by dependency injection in a following chapter. We can give an example of how DI makes the application easy to configure, though. We want to call a logging API in production instead of simply logging to the console.

DI provides a nice way to do this.

We can represent the relations between component and services like this, where the arrows mean depends on:

In fact, what we wrote was the short form of:

We are telling the Injector that we want to create a link between a token (the type LoggingService) and the class LoggingService. The Injector is a service which keeps track of the injectable elements by maintaining a registry and is actually injecting them when needed. For the moment, you can see this registry as a map that associates keys, called tokens, with classes. A token can be anything. But it is usually a class reference (as in the above example) or an instance of InjectionToken.

Since, in our example, the token and the class to inject are the same, you can write the same thing in the shorter form:

The token has to uniquely identify the dependency.

We can use the inject function to test how the injector works:

As you can see, we can ask the injector for a dependency with a token. I have provided the LoggingService twice, with two different tokens. The injector will create an instance of LoggingService the first time it is asked to for a specific token, and then return the same instance for this token every time.

This whole example was just to point out a few things:

The fact that the same service instance is used every time we ask for a service is also a well-known design pattern: it’s called a singleton. This is really useful, because it allows a service to hold state that you want to share between several components.

Now, back to our LoggingService. I can write a new class, doing the same job as LoggingService but this time calling an API to aggregate the logs:

We can use the provider declaration to replace LoggingService with our LoggingAPIService:

Now we have a relation like this:

That can be really useful to replace an implementation with another in certain environments and, as we will see soon, when you are writing automated tests.

In our example, we might want to use LoggingService when we are developing our app, and use the real LoggingAPIService when we are in production. One way of doing that is to use another type of provider: useFactory.

In this example, we are using useFactory instead of useClass. A factory is a function with one job, creating an instance. Our example tests a constant and returns the race service with the development or production logging service.

Of course, this example is just to demonstrate the use of useFactory and its dependencies. You could, and should, write:

Declaring a constant for IS_PROD is really bothering: maybe we can use dependency injection too? I’m pushing things a bit as you can see :) You don’t necessarily need to force all things in DI, but this is just to show you another provider type: useValue.

One last crucial thing to understand in Angular: there are several injectors in your app. In fact, there is one injector per component, and this injector inherits from the injector of its parent.

Let’s say we have an app looking like:

We have an application with a root component App, which has a child component Races.

When we bootstrap the app, we create the root injector for the application. Then, every component will have its own injector, inheriting its parent one.

When you register a service using the recommended providedIn: 'root', you add these services to the root injector.

It means that when we inject a dependency in a component, Angular begins its search in the current injector. If it finds the dependency, perfect, it returns it. If not, it will do the same in the parent injector, and again, until it finds the dependency. If it doesn’t find the dependency anywhere, it throws an exception.

From this, we can deduce two things:

The @Component decorator can take another configuration option, called providers. This providers attribute expects an array of providers, similar the providers option of bootstrapApplication().

We can thus imagine a Races that would declare its own LoggingService provider:

In this component, the provider with the token LoggingService will always give an instance of LoggingAPIService, regardless of what was defined in the root injector. It’s really useful if you want to have a different instance of a service for a given component.

Here we have:

The injection will then be resolved as:

If the service contains state that belongs to a specific component instance, then it should be provided by that component. For stateless services, or services that contain global state, they should be provided in root.

We’ve seen above that we can define tokens to identify services. We’ve also seen that there are two ways to get a dependency: calling the inject function, or declaring the dependency as an argument of the constructor.

When a token is used to identify a service, we can pass this token as argument to the inject function to get the associated service.

It’s also possible to get the service associated with the token when using constructor injection, thanks to the @Inject() decorator.

The above example uses a token BACKEND_URL which identifies a simple value stored in the injector. This token is defined like this:

We then use this token in the providers of the application to define its value:

Or you can register it directly with providedIn:

Angular itself uses this token mechanism, and allows us to define the locale of the application for example, by using the token LOCALE_ID:

But we’ll talk about it later when we see how to internationalize your application!

Angular comes with a few built-in services. Some of them will be discussed in dedicated chapters. For now, let’s talk about two of them.

The basic principle of reactive programming is to try to define the logic in a declarative way, by defining events and telling how to react to those events, instead of doing it in an imperative way. This sounds very abstract, and it is. So let’s try to illustrate this with a basic example.

Let’s say you have a circle, and you need to store its radius as well as its circumference. And you want to be able to change the radius of the circle. Doing that should of course change its circumference accordingly. One way (the imperative way) of doing this is to use two properties:

Every time you change the radius, you need to remember that you also need to change the circumference accordingly.

Another way of doing this is to rely on a reactive primitive, and to declaratively specify that the circumference must be recomputed every time the radius changes. Changing the radius can thus be seen as an event, and we can react to this event by changing the circumference. The reactive primitive we could use here is a signal:

What if we had a component taking the ID of a race as input, and we wanted this component to show the details of that race? Things get more complicated here, because getting the details of the race is an asynchronous operation. We can’t just use a computed signal to "compute" a race based on its ID. Besides, if the ID changes two times in a row, the fetching of the first race should be cancelled before fetching the second one: we’re not interested anymore in the first one.

We might also have to send two different HTTP requests to get the full details of the race, and we would then need to wait until we have both responses before displaying it.

Being able to declaratively express that every time an input changes, we have to make two asynchronous calls, cancel the two previous ones if any, wait for the two calls to complete, and finally display the result, would be great.

That’s the kind of stuff for which RxJS shines. It provides another reactive primitive: an Observable, which represents a stream of synchronous or asynchronous events. It also comes with plenty of functions and operators that allow transforming, filtering, combining these streams of events.

Angular, since its first version, has chosen to depend on RxJS, and uses observables to represent events and things that change over time. For example, the result of a call to the HttpClient is an Observable. The changes of parameters of a route are modeled as an Observable. The changes of the value of a form are modeled as an Observable.

RxJS is not a free meal though. It’s quite complex to learn and master. Thinking in a reactive way doesn’t come naturally to most developers. And Angular has signals now, which provide another reactive primitive that sometimes overlaps with what RxJS provides. So the general direction that Angular has decided to follow is to try not to depend on RxJS anymore, but to make the usage of RxJS inside Angular applications as smooth as possible, by providing interoperability functions.

An Observable is a stream of events, that has a well-defined, albeit flexible lifecycle.

When you subscribe to an observable, it starts emitting events. It can emit 0, 1, N or even an infinity of events. The emission can be synchronous or asynchronous. The events can be anything (an HTTP response, a form value, etc.): it depends on the type of the Observable.

An observable can signal its completion. After the completion, you know that it won’t emit any event anymore. And you’re thus also unsubscribed: why would you keep listening to something that won’t say anything anymore?

In case something goes wrong (for example, you subscribed to send an HTTP request and get an HTTP response but the server is down), an observable can also signal an error. After an error, you also have the guarantee that it won’t emit any event anymore (nor signal a completion). And you’re thus also unsubscribed.

You can create various kinds of observables using RxJS functions. Many RxJS functions are used to transform an observable into another one. Those functions are called operators.

For example:

There are much more operators than these. We would need a whole book to go through all of them. But hopefully you get an idea of what operators can do. If you want to have a good visual representation of what the RxJS functions and operators do, go to rxmarbles.com, or consult the official RxJS documentation.

So, if you have an observable of numbers and want to multiply each by 2, then filter those under 5, and print them, you can do:

The observable in the above example emits synchronously: as soon as we subscribe, the numbers are emitted one by one. When the call to subscribe returns, all the numbers have already been printed to the console.

But observables are usually asynchronous. They can for example represent DOM events that will happen in the future:

When subscribing to such an observable, the function you pass will be executed later, every time the user releases a key in the text field. If you’re not interested anymore in those events, you’ll have to unsubscribe. The simplest way to do that is to call unsubscribe on the Subscription returned by subscribe. There are other ways to unsubscribe, that will be discussed later.

You might also have to handle errors. The subscribe method accepts an object as an argument instead of a simple callback function. This object can define a callback to handle events (named next), and a callback to handle errors (named error).

Here the mapping function throws an exception, so the error callback will log it.

Finally, if the observable completes, you can know about it too by providing a third handler. Here, the range function creates an observable which emits events events from 1 to 5 and then signals its completion:

Now, how can we use RxJS to declaratively display the details of a race whenever the race ID changes? The race ID is an input, which is a signal. But to use RxJS, we would need to have an Observable, not a signal. No issue. Angular provides a toObservable() function that transforms a Signal<T> into an Observable<T>. Internally, it uses an effect to know when the signal changes, and make the observable emit its new value.

So we can do:

We now need to fetch the details of the race whenever the observable emits, and cancel the previous ongoing fetch if any. That’s a job for the switchMap operator. We’ll talk about it in more details in a future chapter.

Now that’s fine, but how can we display the race? We’ll need to subscribe to the observable, and store the emitted race in a signal so that the template can display it. We could do that:

But then we should also unsubscribe when the component is destroyed. There’s a better way. Angular also provides a function to transform an Observable<T> into a Signal<T | undefined>. You guessed it, it’s named toSignal.

Internally, toSignal subscribes to the observable. And it automatically unsubscribes when the component is destroyed.

Are you wondering why it creates a Signal<RaceModel | undefined> and not a Signal<RaceModel>? Well, the answer is logical. An observable is usually asynchronous. It’s the case here. So it only emits its first race once it has received the response from the HTTP server. Meanwhile, there’s no race that can be stored in the signal, so its value is undefined. You can pass an option to toSignal if you prefer a having something else than undefined as the default value, or if you know that the observable emits synchronously.

I love automated testing. My professional life revolves around the test progress bar going green in my IDE, patting me in the back for doing my job properly. And I hope you do care about tests too, as they are the only safety net we have when we write code. Nothing is more tedious than manually testing code.

Angular does a great job to let us easily write tests. So did AngularJS 1.x, and that’s partly why I loved using it. As in AngularJS 1.x, we can write two types of tests:

The first ones are there to verify that a small unit of code (a component, a service, a pipe…​) works correctly in isolation, i.e. without considering its dependencies. Writing such a unit test requires you to execute each of the component/service/pipe methods, and check that the outputs are what we expected regarding the inputs we fed it. We can also check that the dependencies used by this unit are correctly called: for example we can check that a service will do the correct HTTP request.

We can also write end-to-end tests. Their purpose is to emulate a real user interacting with your app, by starting a real instance and then driving the browser to enter values in inputs, click on buttons, etc. We’ll then check that the rendered page is in the state we expect, that the URL is correct - whatever you can think of.

We’re going to cover all this, but let’s begin with the unit test part.

As we saw earlier, unit tests are there to check a small unit of code in isolation. These tests can only verify a small part of your app works as intended, but they have several advantages:

One of the core concepts of unit testing is isolation: we don’t want our test to be biased by its dependencies. So we usually use "mock" objects as dependencies. These are fake objects that we create just for testing purposes.

To do this, we are going to rely on a few tools. First we need a library to write tests. One of the most popular (if not the most popular) is Jasmine, so we are going to use it!

The TestBed class will help us to declare fake dependencies.

Even though Angular allows creating applications without defining Angular modules, its TestBed utility is still designed around the concept of a testing module, that can be configured pretty much the same way as an Angular module. Since we’re using standalone components, the main purpose of that testing module will be to provide fake dependencies instead of the actual ones. The TestBed.configureTestingModule method allows you to specify an array of providers, that will supersede the actual dependencies injected in our component, pipe, directive or service under test.

For the sake of the example, let’s say that my RaceService uses the local storage to store the races, with a key 'races'. Your colleagues have developed a service called LocalStorageService that deals with the JSON serialization, etc. that our RaceService uses. The list() method looks like:

Now, we don’t really want to test the LocalStorageService service: we just want to test our RaceService. That can easily be done by leveraging the dependency injection system to give a fake LocalStorageService:

to RaceService in our test, using provide:

Great! But I’m not completely satisfied with this test. Creating a fake service by hand is tedious, and Jasmine can help us spy on the service and replace its implementation with a fake one. It also allows you to verify that the get() method has been called with the proper key 'races'.

The next step after testing a simple service is to test a component. A component test is slightly different because we want to test not only the code inside the TypeScript class, but also the template of the component.

Let’s start by writing a component to test. Why not our Pony component? It takes a pony as an input and emits an event ponyClicked when the component is clicked.

It comes with a fairly simple template: an image with a dynamic source depending on the pony color, and a click handler.

To test such a component, you first need to create an instance. As our component has inputs, it is fairly common to create a wrapper component in the test, and to create an instance of this test component (so we can easily pass inputs ou test the outputs). To do this, we use the TestBed. This class comes with a utility method, named createComponent, to create a component. The method returns a ComponentFixture, a representation of our component.

Here, we follow the "Given/When/Then" pattern to write the unit test. You’ll find a whole literature on the subject, but it boils down to:

We can also test if the component really emits an event:

Let’s have a look at another component:

and its test:

Here we query all the directives of type Pony and test if the first pony is correctly initialized.

You can get the components inside your component with children or query them with query() and queryAll(). These methods take a predicate as argument that can be either By.css or By.directive. That’s what we do to get the ponies displayed, as they are instances of Pony. Keep in mind that this is different from a DOM query using querySelector(): it will only find the elements handled by Angular, and will return a ComponentFixture, not a DOM element (so you’ll have access to the componentInstance of the result, for example).

When testing a component, we sometimes want to create a test host component that uses it. That allows testing that the properties and outputs bindings work well. Let’s take our pony component for example. In order to test that we can provide a running input, or that we can omit it to use its default value, we should test it with a parent component passing the running input, and also test it with a parent component not passing it.

Fortunately, the TestBed allows overriding the template of the test host component (or any other component, by the way):

We can go further than that. It’s also possible to call TestBed.overrideComponent() to set, add, or remove any property of the decorator of a component (template, providers, imports, etc.). That is sometimes useful, for example to test a parent component with a stub child component instead of an actual child component, in order to make the test simpler. We could for example replace the Pony in the imports of Race by a PonyStub which has the same selector, inputs and outputs, but which does nothing.

Now you’re ready to test your app!

Angular tests can quickly be very verbose. As we don’t really like that, we wrote a tiny open-source library called ngx-speculoos.

Instead of writing a test looking like this:

you can write a cleaner and simpler test with ngx-speculoos:

You can go one step further with the custom matcher for Jasmine we wrote:

Give it a try!

End-to-end tests are the other type of tests we can run. An end-to-end test consists in really launching your app in a browser and emulating a user interacting with it (clicking on buttons, filling forms, etc.). They have the advantage of really testing the application as a whole, but:

As you may guess, you don’t have to choose between unit tests and e2e tests: you will combine both to have great coverage, and some guarantees that your complete application runs as intended.

Angular CLI doesn’t have a default solution for E2E tests. After all, these tests don’t even need to know that the application is built with Angular, so you can choose the tool you want. Some tools can be integrated inside the CLI though, so that you can run ng e2e to serve the app and then run the end-to-end tests.

The most popular tools are probably Cypress and Playwright. Nowadays, our preference goes to Playwright, which is free, well maintained by Microsoft, and can run tests in parallel on the three major browsers (Chrome, Firefox and Safari).

The @angular/common/http module offers a service called HttpClient that you can inject in any constructor. This service isn’t available by default in an Angular application. You need to configure the application to use it.

To do this, we need to configure a provider when bootstrapping the application.

Once this is done, you can inject the HttpClient service wherever you need it:

By default, the HttpClient service will do AJAX requests using XMLHttpRequest.

It offers several methods, matching the most common HTTP verbs:

If you used the $http service in AngularJS 1.x, you might remember that it heavily relied on Promises. In Angular, however, all these methods return an Observable object.

A few advantages come with the use of Observables for HttpClient like the ability to cancel requests, to retry, to easily compose them, etc.

Let’s start by fetching the races available in PonyRacer. We’ll assume that a backend is already up and running, providing a RESTful API. To fetch the races, we’ll send a GET request to a URL like 'http://backend.url/api/races'.

Usually, the base URL of your HTTP calls will be stored in a variable or a service, that you can easily configure depending on your environment. Or, if the REST API is served by the same server as the Angular application, you can simply use a relative URL: '/api/races'.

Using the HttpClient service, such a request is straightforward:

Note that you don’t need to deserialize the response body from a string to a JavaScript array or object. That is done automatically by Angular. However, Angular won’t make any check to verify that the JSON in the response indeed conforms to the generic type you specified. It’s up to you to make sure that you’re using the correct generic type, and that the RaceModel interface indeed matches with the JSON that the server sends back.

This returns an Observable, to which you can subscribe to receive the response.

The response body is the most interesting part, and it is directly emitted by the Observable:

The most typical use case is to have a service with methods that return an observable:

And then subscribe to this observable in a component using toSignal:

Of course, you can also have access to the full HTTP response. The object returned is then an HttpResponse object, with a few fields like the status code, headers, etc.

The observable will throw an error if the response status is different from 2xx or 3xx, and the error is then of type HttpErrorResponse.

Sending data is fairly easy too. Just call the post() or put() method, with the URL and the object to post:

Once again, no need to serialize the race object being sent to JSON. Angular does that for you. The generic type RaceModel here is, just as with the get() method, the type of the response body. So this example endpoint takes a RaceModel as input and returns the created RaceModel.

I won’t show you the other methods - I’m sure you get the idea.

This kind of work will usually be done in a dedicated service. I tend to create a service, like RaceService, where all the job is done. Then, my component just needs to subscribe to my service method, without knowing what’s going on under the hood.

You can also leverage the power of RxJS to retry a failed request a few times, for example.

Of course, you can tune your requests more finely. Every method takes an options object as an optional parameter, where you can configure your request. A few options are really useful and you can override everything in the request.

params represents the URL search parameters (also known as the query string) to add to the URL.

The headers option is often useful to add a few custom headers to your request. It happens to be necessary for some authentication techniques like JSON Web Token for example:

Interceptors are interesting when you want to…​ intercept requests or responses in your application.

For example, if you want to intercept every request to add a specific header to some of them, you can now write an interceptor like this one:

Note that you have to clone the request to update it (requests are immutable).

Then configure the HTTP client provider so that it uses the interceptor:

Now every request will go through the interceptor, and receive the custom header if needed (here the requests to the Github API).

You can also intercept the response, which can be handy to handle errors in a generic way:

This is one of the cases where the inject() function needs to be used: since the interceptor is defined as a function, there is no constructor allowing to inject the dependencies, but the inject() function allows getting them.

Sometimes you want to give some context to an interceptor. Since Angular v12, it is possible thanks to HttpContext. The context uses a type safe token (HttpContextToken), so you can define something like this in your interceptor:

And change the interceptor to:

All HTTP methods accept a context option, which is a Map that you can build in a type-safe way by using the token defined previously:

We now have a service calling an HTTP endpoint to fetch the races. How do we test it?

In a unit test, you don’t want to really call the HTTP server: that’s not what we are testing. We want to "fake" the HTTP call to return fake data. To do this, we can replace the dependency to the HttpClient service with a fake implementation by importing the HttpClientTestingModule. We can then use a class provided by the framework called HttpTestingController to fake the HTTP responses.

And you can also add a few assertions on the underlying HTTP request:

And we’re done!

Let’s start using the router. It is an optional module, that is thus not included in the core framework.

Similarly to the HTTP client, you have to provide the router in your application if you want to use it. But for that, we need a configuration to define the mapping between URLs and components. We can do this with a dedicated file, generally named like app.routes.ts, and containing an array representing the configuration:

Then we need to provide the router in our application, initialized with the proper configuration:

As you can see, the Routes is an array of objects, each one being a…​ route. A route configuration is usually a pair of properties:

You may be wondering where the component will be inserted in the page, and that’s a good question. For a component to be included in our app, like the Races in the example above, we must use a special tag in the template of the primary component: <router-outlet>.

This is, of course, an Angular directive, whose only job is to act as a placeholder for the template of the component of the current route. Our app template would look like:

When we navigate, everything will stay (the header, main and footer here) and the component matching the current route will be inserted just after the RouterOutlet directive.

How can we navigate between the different components? Well, you can manually type the URL and reload the page, but that’s not very convenient. And we don’t want to use "classic" links, with <a href="…​"></a>. Indeed, clicking on that link makes the browser load the page at that URL, and restart the whole Angular application. But the goal of Angular is to avoid such page reloads: we want to create a Single Page Application. Of course, there is a built-in solution.

In a template, you can insert a link with the directive RouterLink pointing to the path you want to go to. The RouterLink directive can receive a constant representing the path you want to go to or an array of strings, representing the path and its params. For example in our Races template, if we want to navigate to the Home, we can imagine something like:

At runtime, the link href will be computed by the router and will point to /.

The RouterLink directive can be used with the RouterLinkActive directive which can set a CSS class automatically if the link points to the current route. This allows you, for example, to style a menu item as selected when it points to the current page.

We can even put a reference on this directive, to know if the route is active, and use it in the template:

It’s also possible to navigate from the code, by using the Router service and its method navigate(). It’s often handy when you want to redirect your user after an action:

The method takes an array of parameters, with the path you want to navigate to as the first element.

It is also possible to have parameters in the URL, and it’s really useful to define dynamic URLs. For example, we want to display a detail page for a pony, with a meaningful URL for this page, like ponies/id-of-the-pony-/name-of-the-pony.

To do so, let’s define a route in the configuration with one (or several) dynamic parameters.

We can then define dynamic links with routerLink:

Of course, the target component needs to access those parameters to be able to load and display the pony with the given identifier. To get the value of the parameters, the router provides a service, that you can of course inject in the component, named ActivatedRoute. This object has a handy property: snapshot. This property has all the parameters of the URL in paramMap!

As you may have spotted, we are using snapshot. Is there a non snapshot version? Yes there is. And it provides a way to subscribe to parameter changes, with, you guessed it, an observable. This observable is called paramMap.

Here we subscribe to the observable offered by ActivatedRoute. Now, every time the URL changes from /ponies/1 to /ponies/2 for example, the paramMap observable will emit an event, and we’ll fetch the correct pony to display on screen.

What you have just learnt should cover your basic routing needs. But the router goes well beyond this and offers many additional features. Covering them all in detail is quite a big task, and you can feel overwhelmed when trying to learn them all.

This section will try to present most of the additional features as concisely as possible, by explaining what they’re useful for.

A common use-case is to have a URL simply redirect to another URL in the application. This can happen because you want, for example, the root URL of your news app to redirect to the /breaking news category, or an old URL to redirect to a new one after a refactoring. This is possible using

In the above example illustrating a redirect, I applied a strategy for matching the route: 'full'. The default strategy is 'prefix', which matches a route with a URL when the URL starts with the path of the route. If we used this default strategy here, all URLs would redirect to /breaking, since all URLs start with an empty string.

The matching strategy consists in finding the first route that matches the complete URL. So, for example, if you define routes like

and the URL is races/new, the component that the router will activate is in fact the Race. Indeed, races/:id matches with races/new and comes first in the list of routes. To solve this problem, change the order of the routes:

Routes can have children. This can be useful for several reasons:

As we have seen before, when the router activates a route, the component of the route is inserted in the page at the location marked by the router-outlet directive.

This mechanism can in fact be used in nested components, too. Suppose you have a complex page to display the profile of a pony. This page would display its name and portrait at the top, and would have several tabs at the bottom: one to display its birth certificate, one to display its track record, and one to display journalist reviews about this pony. You want to have a URL for each tab, in order to be able to directly link to them. But you don’t want to reload the pony and repeat its name and portrait on every on these three tab components.

The solution is to use a nested router-outlet in the template of the Pony, and to define a parent pony route, this way:

When going to the URL ponies/42/reviews, for example, the router will insert the Pony at the location indicated by the main router-outlet, in the root component. The template of Pony, besides the name and the portrait of the pony, contains a second router-outlet. This is where the child Reviews will be inserted.

When going to the URL ponies/42, the pony component will be displayed, but none of the three children components will. You might want to display the birth certificate tab by default. That can be achieved using an empty-path route, redirecting to the birth-certificate route:

Note that, in the above example, the redirect is relative to the ponies/:ponyId route, because it doesn’t start with a /.

Instead of redirecting, you might want to display the birth certificate at the URL ponies/42. This can also be achieved using a child empty-path route:

Some routes of the application should not be accessible to all users, depending on their permissions. Of course, you should hide or disable links pointing to these routes if the user may not access them. You should also make sure that the backend doesn’t allow accessing or modifying resources that the user isn’t authorized to access or modify. But that still won’t prevent users from accessing routes that they’re not allowed to access, who can simply enter their URL in the address bar.

That’s where guards come into play. There are 4 kinds of guards:

Here’s how you would add a CanActivate guard on a route. The three other guards are added in a similar way:

In the above example, loggedInGuard is a function.

The function consists of deciding whether the route can be activated or not (by checking if the user is logged in or not), and in returning a boolean, a Promise<boolean|UrlTree>, an Observable<boolean|UrlTree> or a UrlTree.

The router will navigate to the route if the returned value is true, or if the returned promise is resolved as true, or if the returned observable emits true. If the returned value is a UrlTree, it cancels the current navigation and triggers a navigation to the returned UrlTree.

Here’s what the loggedInGuard function might look like:

Hierarchical routes combined with empty-path routes can be very handy when you want to apply a guard on several routes at once. For example, if you want both the races and the ponies routes to be accessible only to logged in users, instead of

you can introduce an empty-path, componentless route as a parent. This route won’t consume any URL segment, and won’t activate any component, but its guards will be called when navigating to any of its children:

In a good old multi-page application where the pages are generated server-side, when clicking on a link, here’s what happens: a request is sent to the server, the browser typically shows a spinning icon on the tab, and when the response finally comes back from the server, the URL in the address bar changes and the content of the new page is displayed.

In an Angular single-page application, it doesn’t exactly work that way. The user clicks on a link to display a pony race (for example). The router creates an instance of the Race, and the component sends an AJAX request to load the race. The router immediately inserts the component template at the router-outlet location and changes the URL in the address bar. At this time, immediately after the click, the user sees the new page, but without any race. When the response to the AJAX request comes back, the race is stored in the component and the DOM is updated.

This has advantages and drawbacks:

A resolver allows making the application behave almost like a traditional multi-page application. Instead of letting the race component load the race, you apply a resolver on the route, and the resolver loads the race on behalf of the component.

Like a guard, a resolver can return data synchronously (by returning a race) or asynchronously (by returning a promise or observable of a race). The router only navigates to the route once the promise has been resolved, or once the observable has completed with at least an emitted race. Here’s what a resolver for a race would look like:

As you can see, it’s a simple function, which uses the activated route snapshot passed by the router to get the value of the raceId parameter, and returns an Observable<RaceModel>.

Here’s how the resolver would be applied to the route:

As you can see, the resolver is associated with an object key that I chose to name race. This is the key that the router will use to store the loaded race into the data of the activated route snapshot. So the race component can simply obtain the race the following way:

Note that, if you navigate from a route to the same route, but with different parameters (for example, if you have a Next race link on the page), then the guards and the resolvers applied to the route are called again. The component, in that case, will still be reused, and should still subscribe to an observable to get the race (or just store the observable in the component and use the async pipe in the template):

Resolvers have many advantages over loading data from the activated component:

The only drawback I can find is that, when you know that loading the data is slow (because it requires substantial computations or external service calls by the server), then the application can feel a bit unresponsive: you click on a link, and nothing happens until the data has been loaded. This is where loading the data from the activated component and displaying a loading message or animation can be more user-friendly. Another workaround would be to rely on router events to display this loading message.

The router emits several events when navigating to a route. You can be notified of these events by injecting the Router service and subscribing to its events observable. The emitted events have several types that you can filter using event instanceof NavigationStart (for example). Here are the various types of router events:

There are other kinds of events for the route configuration loading (RouteConfigLoadStart, RouteConfigLoadEnd, RoutesRecognized) and, since version 4.3, for the resolvers (ResolveStart, ResolveEnd) and guards (GuardsCheckStart, GuardsCheckEnd). Version 5.0 added more fine-grained navigation events (ChildActivationStart, ChildActivationEnd). Version 6.1 added a Scroll event, along with the scrollPositionRestoration configuration option that allows you to restore the scroll position when navigating back to a component.

We’ve seen before that routes can have parameters. For example, the route races/:raceId has one parameter named raceId, and the value of this parameter, when navigating to /races/42 is the string '42'. But this route can actually have additional parameters named matrix parameters.

If you navigate to the URL

then the params and paramMap properties of the activated route will contain two additional parameters 'foo' and 'baz' having the values 'bar' and 'wiz'.

Those matrix parameters are specific to the route. So, for example, if the URL is

then the component associated with the ponies segment won’t have foo nor bar in the parameters of its activated route. Only the component associated with the races/42 segment will.

To navigate to such a URL, you would use the following code:

or an equivalent router link:

Query parameters, on the other hand, are shared by all the route segments. They look like this in the URL:

These query parameters are accessible from any route, using the queryParams or queryParamMap property.

To navigate to such a URL, you would use the following code

or the equivalent router link:

Finally, we’ve seen that resolvers allowed adding properties to the data property of the activated route, before the route is activated. It’s also possible to add additional data to a route directly from its configuration. This can be useful when the same component can be used in two different contexts for example:

We saw that the parameters and data of the route are accessible from the component associated with the route, via observables on the ActivatedRoute object.

Since Angular v16, it’s possible to automatically bind the route parameters and data to the component inputs.

To do so, you need to configure the router with withComponentInputBinding:

With this option, a component can declare an input with the same name as a route parameter or data, and Angular will automatically bind the value of the parameter or data to this input.

We can then use this input as a regular input, and react to its change with toObservable and toSignal:

This section will conclude this long chapter about the Angular router.

When the application grows in size and features, loading the whole application at once can become a problem: the application bundle is too large and takes too much time to load and parse. Moreover, some parts of the application are only used by some users of the application, or are used rarely, and loading them eagerly is a waste of time and bandwidth. This is where lazy-loading is useful.

Lazy loading consists in splitting the application into several JavaScript bundles, by loading child routes lazily. The application routes array, instead of defining all the routes of the application, only contains the main, eagerly-loaded routes, as well as parent routes with lazy-loaded children, which are thus unknown initially.

When the user navigates to the path of an unknown child route, then the Angular router loads the JavaScript bundle containing the child routes (and their associated components and services), and adds the child routes, components and services to the application.

To illustrate how we can configure lazy loading, we will assume that you want to define an admin section in your application, that should be lazy loaded.

The first step is to define an admin component, and at least one route for this component in a file named admin.routes.ts:

The final step (yes, that’s all it takes) is to add a parent route in the main app.routes.ts file, and tell the router to lazy-load the admin routes when navigating to that route (or any child route it might have):

As you can see, this is achieved by using the loadChildren property of the route definition and the dynamic import function from TypeScript.

When building this application, Angular CLI parses the route configurations and detects that the admin child module is lazy-loaded. Without any more work on your part, it generates an additional JavaScript bundle for the admin module (named 0.chunk.js), and generates the necessary JavaScript to load this bundle when the router requires './admin/admin.routes'.

You can even simplify the import if you use a default export for the module:

Then the router will automatically "unwrap" the import:

Finally, if (as above) all you want to do is to lazy-load a single component for a given route, then it’s even easier: you don’t even have to define an additional routes file. The component can be lazy-loaded directly:

Forms have always been extra polished in Angular. That’s one of the features that was the most demoed in 1.x, and, as pretty much every app has forms, it won the hearts of a lot of developers.

Forms are hard: you have to validate the inputs of your user, display errors, you can have fields required or not, or depending on another field, you want to react to some field changes, etc. We also need to test these forms, and that was impossible to achieve with a unit-test in AngularJS 1.x. It was only feasible with an end-to-end test, which can be slow.

In Angular, the same care has been applied to forms, and the framework gives us a nice way to write our forms. In fact, it gives us several ways!

You can either write your form using only directives in your template: that’s the "template-driven" way. From our experience, it shines when you have a simple form, with not much validation.

The other way is the "code-driven" way, where you will write a description of the form in your component, then use directives to bind this form to the inputs/textareas/selects in your template. It’s more verbose, but also more powerful, especially if you want to do add custom validation, or to generate dynamic forms.

Let’s go through the same use case twice, using each way, and see the differences.

We are going to write a simple form, to be able to register new users in our awesome PonyRacer app. We need a base component for each use case, so let’s begin with this:

Nothing fancy: a component with a simple template containing a form. In the next few minutes, we will build a form allowing you to register a user with a username and a password.

For both methods, Angular will create a representation of our form.

In the "template-driven" way, it’s pretty much automatic: we just need to add the proper directives in the template and the framework takes care of the form representation creation.

In the "code-driven" way, we create this form representation manually, and then bind the form representation to the inputs using directives.

Behind the scenes, a form field, like an input or a select, is represented by a FormControl in Angular. It is the smallest part of a form, and it encapsulates the state of the field and its value.

A FormControl has several attributes:

It also offers some methods like hasError() to check if the control has a specific error.

So you can do something like this:

Note that you can pass an argument to the constructor, and that this argument will be the value.

These controls can be grouped in a FormGroup to represent a part of the form and have dedicated validation rules. The form itself is a group.

A FormGroup has the same properties as a FormControl, with a few differences:

It offers the same methods as FormControl like hasError(). It also has a method get() to retrieve a control in the group.

You can create one like this:

Let’s begin with a "template-driven" form!

With this method, we are going to use a bunch of directives in our form, and let the framework build the necessary FormControl and FormGroup instances. For example, the NgForm directive transforms the form element into its powerful Angular version - think of it as the difference between Bruce Wayne and Batman.

All the directives we need are included in the FormsModule module, so we need to import it in each component using a template-driven form.

FormsModule contains the directives for the "template-driven" way. We’ll see later that there exists another module, ReactiveFormsModule, in the same package @angular/forms, which is needed for the "code-driven" way.

Let’s add the submit button:

I added a button, and defined an event handler for ngSubmit on the form tag. The ngSubmit event is emitted by the NgForm directive when submit is triggered. It calls the register() method of our controller, which will be implemented later.

You might wonder why there is an NgForm directive available on the form element, even though it doesn’t have any specific attribute. It’s simply that the selector of the NgForm directive is form (it is actually a bit more specific than that), which means that every standard HTML form element actually triggers the creation of an NgForm directive, as long as the FormsModule has been imported.

Last thing: our template will quickly grow, so let’s extract it to a dedicated file, using templateUrl:

In the "template-driven" way, you write your forms pretty much like in AngularJS 1.x, with a lot of things in your template and not many in your component.

In its simplest form, you just add ngModel directives to your form template and that’s all. The NgModel directive creates the FormControl for you, and the form automatically creates the FormGroup. Note that you have to give a name to the input, which will be used by the framework to create the FormGroup.

Now of course we need to do something for the submission, and to get hold of the user name and password. To achieve that, we can define a local variable and assign it to the NgForm object created by Angular for the form. Remember these from the Template chapter? Here, we are going to define a variable, userForm, referencing the form. We can do that because the form directive exports the NgForm directive instance, which has the same methods as the FormGroup class. We’ll see the exporting part in more detail when we study how to build advanced directives.

Our register method is now called with the form value as the argument:

This is only one-way data-binding though. If you update the field, the model will be updated, but updating the model will not update your field value. But ngModel is more powerful than you think!

In AngularJS 1.x you had to build your forms mostly in your templates. Angular introduces an imperative way, which allows you to construct the form programmatically rather than through a template.

Now we can handle forms directly in our code. It’s more verbose but more powerful.

To build a form in our component code, we’ll use the abstractions we talked about: FormControl and FormGroup.

With these basic elements we can build a form in our component. But instead of writing new FormControl() or new FormGroup(), we will use a helper class, FormBuilder, that we can inject:

The FormBuilder is a helper class, with a handful of methods to create controls and groups. Let’s start simple, and create a small form with two controls, a username and a password.

We created a form with two controls. You can see that each control is created with the value ''. That’s the same as using the helper method control() of the FormBuilder with this string as parameter, and the same as calling the new FormControl('') constructor: the string represents the initial value you want to display in your form. Here it is empty, so the inputs will be empty. But you can have a value here, of course, if you want to edit an existing entity for example. The helper method can also have other specific attributes, as we will see later.

We need to implement the register method. As we saw, the FormGroup object has a value attribute, so we can simply log its content with:

We now need to do some work in the template. We are going to use other directives than those we saw for the "template-driven" forms. These directives are in the ReactiveFormsModule, that you have to import into your component. Their names begin with form instead of ng as was the case for the "template-driven" forms.

The form needs to be bound to our userForm object, thanks to the formGroup directive. Each input field is bound to a control, thanks to the formControlName directive:

We want to bind our component’s attribute userForm object to formGroup, so we use the bracket notation [formGroup]="userForm". Each input receives the formControlName directive with a string literal representing the control it is bound to. If you specify a name that does not exist, you will have an error. As we pass a value (and not an expression), we don’t put the [] around formControlName.

And we’re done: clicking on the submit button will log an object containing the username and the chosen password!

If you need to, you can update the value of a FormControl from your component, using setValue():

Validation is usually a big part of form-building. Some fields are required, some depend on one another, some should be in a specific format, some should not have a value greater or lower than X, for example.

Let’s start by adding basic validation rules: all our fields are required.

Of course, our user should not be able to submit the form while there are still errors left, and these errors should be perfectly displayed.

If you try the examples, you will see that even if the fields are required, we can still submit our form. Maybe we can do something about that?

We know that we can easily disable a button using the disabled property, but we need to give it an expression reflecting the state of the current form.

Whatever way you choose to create your forms, Angular does another awesome job for us: it automatically adds and removes CSS classes on each field (and on the form) to allow us to add some visual style.

For example, a field will have the class ng-invalid if one of its validators fails, or ng-valid if all the validators succeed. That means you can easily add some style, like a nice red border around the fields failing the validation:

Another useful CSS class is ng-dirty which will be present if the user has changed the value. Its opposite is ng-pristine, present if the user never changed the value. I usually display the red border only when the user has changed the value at least once:

Finally, there is a last CSS class: ng-touched. It will be present if the user enters and leaves the field at least once (even if she/he did not change the value). Its opposite is ng-untouched.

When you display a form for the first time, a field will usually have the CSS classes ng-pristine ng-untouched ng-invalid. Then, when the user enters and leaves the field, it switches to ng-pristine ng-touched ng-invalid. When the user changes the value, still for an invalid one, we’ll have ng-dirty ng-touched ng-invalid. And finally, when the value is valid: ng-dirty ng-touched ng-valid.

Pony races are an addictive game so you are only allowed to register if you are over 18. And we want the user to enter the password twice, to be sure she/he hasn’t made a mistake.

How do we do this? We create a custom validator.

To do so, we just have to create a method that takes a FormControl, tests its value and returns an object with the errors or null, if the validation passes.

Our validation method is pretty easy: we take the value of the control, we build the date, check if the 18th birthday is before now and return an error with the key 'tooYoung' if not.

Now we need to include this validator.

Until now, we just had one group: the complete form. But we can declare groups inside a group. That’s very useful if you want to validate a group of fields together like an address, or, like in our example, if you want to check if the password and its confirmation match.

The solution is to use a code-driven form.

First, create a new group, passwordGroup with the two fields and add it in the group userForm with the key passwordForm:

As you can see, we have added a validator on the group, passwordMatch, that will be called every time one of the fields changes.

Let’s update the template to reflect the new form, using the formGroupName directive:

Voilà!

A last cool feature when using a code-driven form: you can easily react to value changes, using the observable valueChanges. Reactive programming FTW! For example, let’s say we want our password field to display a strength indicator. We want to compute the strength at every change of the password value:

or with toSignal:

Now we have a passwordStrength field in our component instance, that we can display to our user:

We are leveraging RxJS operators to add a few cool features:

RxJS can do tons of work for you: imagine coding yourself what we just did in two lines. It can also easily combine with HTTP work, as the HttpClient service uses observables too.

Angular 5.0 introduced the possibility of waiting for the blur or the submit event to update the field’s value and validity. To do so, the FormControl constructor accepts an options object as the second parameter, to define the synchronous and asynchronous validators, and also the updateOn option. Its value can be:

It’s also possible to configure this option on a group of fields all at once:

The same feature is available in template-driven forms, with the ngModelOptions input of the NgModel directive:

or globally on a form with the NgFormOptions input (which appeared with Angular 5.0) of the directive NgForm:

FormControl and FormGroup are not the only entities that we can use to build a form. If you want a part of the form to be dynamic, you can use a FormArray or a FormRecord.

FormArray is an array of controls that contains the same types of value. A typical example is a form where you want the users to be able to add/remove values, like for example tags when editing a blog post:

Then you can iterate on the controls in the template, and have buttons to add/remove a tag:

The value of the FormArray is an array of strings in this example. Of course, form arrays can contain any kind of controls. For example, if you want to add lines to an invoice, the FormArray will contain form groups with a label, quantity, price, etc.

FormRecord is another entity you can use to build forms. It has been introduced in Angular v14, and allows building key-value maps.

Let’s say you want to build the packing list for a trip, with the possibility to add and remove items, and to check/uncheck them. FormRecord can help in that case:

Then you can iterate on the controls in the template, and have buttons to add/remove equipment:

The value of the FormRecord will then be an object, with the equipment name as the key and a boolean as value. For example:

Until version 14 of Angular, forms were not typed. What does that mean?

Well, the value of a FormControl or a FormGroup was of type any, which is obviously far from being ideal.

If you upgrade an application from version 13 to version 14, in order not to break your code, the types FormControl, FormGroup and FormArray are replaced with UntypedFormControl, UntypedFormGroup and UntypedFormArray.

The original types are now typed. But what are the concrete changes in Angular 14?

The form elements became generic. So, we now use FormControl<string> for example, to indicate that the value of the control is a string. The FormGroups, on the other hand, take the type of the controls that they contain. For example, a FormGroup used to register a user will have the type

It’s verbose, but don’t panic: these generic types are, most of the time, inferred by the compiler when the variables are initialized.

As you may have noticed, the templates can quickly become very verbose with all the error messages that we have to repeat for each error type on each field, in every form. You are quickly stuck with very long ngIf and copied/pasted boilerplate between components.

As we find it distasteful as well, we wrote a tiny open-source library to make it easier (heavily inspired by ngMessages in AngularJS): ngx-valdemort.

Instead of

the library allows you to write:

We can even do better by defining default messages once and for all:

And then simply use:

We provide an integration with Bootstrap and Material, to have error messages with a coherent style if you use one of these CSS frameworks. Give it a try, you won’t regret it!

HTML defines a large set of input types: text, password, checkbox, etc. But sometimes these standard types don’t fit the bill.

Angular allows defining custom components, and it’s actually possible to make them act as Angular form controls, i.e. bind them to a form control by applying the NgModel directive or the FormControlName directive, and thus integrating them in a form.

The glue to implement this binding is an interface provided by Angular: ControlValueAccessor.

Fulfilling its contract is relatively straightforward. You have to

We will illustrate all of this using a custom rating component. This component allows rating a movie, for example, by giving it a note between 0 and 5. But instead of using a number or range input, we would like the user to do that by simply clicking one of 6 buttons (that would typically be displayed as star icons, but we’ll leave that out in the following example).

Here’s the code of such a component.

and here is its template:

The code to deal with the two callback functions and the disabled state is boilerplate code that is almost identical in every CVA (ControlValueAccessor).

The interesting part is the handling of the value. Angular calls writeValue() to tell the component what value to display. Here, we simply store the value, and use it in the template to display the first buttons as yellow-filled buttons.

When a button is clicked, we change the value of the component of course, but we must also tell Angular about this change. That’s what allows it to change the value of the form control, trigger the validations, etc.

The disabled state is honored by disabling all the buttons.

And finally, we choose to make the form control touched as soon as one of the rating buttons loses the focus. We do that by calling the provided onTouched callback function when a button fires a blur event.

The last thing we have to do is to register this component as one of the control value accessors of the application. We do that by adding a provider to the rating component’s decorator. Don’t bother too much with the syntax: you can simply copy and paste this snippet every time you define a new CVA.

Voilà. We now have a shiny reusable rating component that can be used to rate something in any form, by simply applying one of the standard Angular form directives to the component:

Angular offers two ways to build a form:

This is maybe the most pragmatic approach: go with template-based and bidirectional binding if you like it, and as soon as you need access to form groups or form controls, for example to add custom validation or reactive behavior, then declare the ones you need in the component, and bind the inputs and divs to them using the appropriate directives.

The "legacy" change detection mechanism is based on a dirty trick: ZoneJS. ZoneJS is a library that has been written for the needs of Angular, but is actually not coupled to it. Its principle is pretty simple, but ugly: it monkey-patches plenty of functions of the browser. Basically, all the functions of the browser that receive a callback function, like setTimeout, setInterval, Element.addEventListener, Promise.then, etc.

The goal of this monkey-patching, for Angular, is to act as a snitch. Every time one of these callback functions is executed, ZoneJS notifies Angular that something has happened.

To illustrate it, let’s take setTimeout as an example. The principle of the monkey-patching is the following one (this is not the actual code):

Why does this help? Thanks to ZoneJS, the framework knows when some code has been executed. It thus knows that some state might have changed. But it still doesn’t know if something actually changed, and even less what has changed.

To have a DOM that is always up-to-date, Angular will thus launch a change detection every time ZoneJS tells it that some code has been executed.

This first part already shows reasons why Angular tries to get rid of ZoneJS by introducing signals:

The second part of the problem is the change detection itself. It’s one thing to know when and how it’s started, but it’s another to know how it works.

First of all, we have to remember that an Angular  application is a tree of components. When the change detection runs, it goes through all the components in the tree, from the root to the leaves. It evaluates all the expressions used in the templates, and compares each result with the previous one. If an evaluation result is not the same, then the DOM is updated. The expression that has a new value could also be used as the input of a child component. In that case, Angular updates the input of the child component and calls its ngOnChanges hook, which might change the state of the child component. Then the child component is checked.

The tree traversal, fortunately for performance, is done only once per change detection. But this comes with another disadvantage: you can introduce a bug if, during the changed detection of a child component, you update its own state or the state of a parent. Since Angular does a single pass, this change will go unnoticed until the next time ZoneJS triggers a new change detection.

Angular forbids you from doing that. During development, each change detection actually does two traversals. If the second traversal detects a change, then Angular throws an error to warn you that you broke the unidirectional data flow principle (the infamous ExpressionChangedAfterItHasBeenCheckedError).

As you can see, change detection is quite brute-force. The expressions in your templates are evaluated many many times. This is why you should make sure they don’t invoke complex, slow functions.

In the previous chapter, we talked briefly about how the framework generates a change detection function for each component.

This is a very interesting and particular point in Angular, which you don’t see in other frameworks: Angular, at the start of your application, will compile your templates and generate dynamic code for each component.

The HTML you write in your templates is never read by the browser directly. Instead, Angular generates a component definition for each component that represents exactly what you wrote in your template. This component definition is inlined in a static field of your component.

Let’s take an example, with our well-known Pony. The template is mainly an image with a bound source property, and a figcaption element with an interpolation.

When Angular compiles this, it first starts by parsing the template to generate what is called an Abstract Syntax Tree (AST). An AST is a tree representing the structure of the template, commonly used by compilers to represent such things. It is the result of the syntax analysis step of the compilation. This AST will then be used to generate the dynamic JavaScript code, a "component definition" per component, inlined in a static field of our component class. A component definition contains several things, and among them the template, represented by a function.

With this function, Angular is able to create the DOM corresponding to our Pony: it basically appends the corresponding HTMLElement to the DOM, for every element.

But how does it handle the change detection? The template function is in fact a little bit longer:

This template function has two parts:

It is called by the framework every time it needs to check if there is a change (see the previous chapter). It basically gets the values of the dynamic bits (the src attribute and the interpolation), and then calls a function of the framework with the index of the element to update, and another one with its property and the new value. The framework then compares the previous value stored for this element and if it changed, updates it, and replaces it with the new value.

This generated code is very fast and can be optimized by JS engines (see the part on monomorphism and inline caching in the previous chapter). This code generation takes some time, so it used to be done in the browser, on the application start. This mode was called the Just in Time (JiT) compilation. The Ivy compiler is now fast enough to do this compilation directly when you run ng serve or ng build. This mode is called Ahead of Time (AoT), and is detailed below.

To sum up, when you are using the JiT compilation: you write TypeScript code and HTML templates, you compile your TypeScript to JavaScript and send the JS and HTML to your users. At runtime, the HTML is then compiled to JS code too.