Taiga UI is an Open Source Angular UI library that helps developers build modern, reliable user interfaces. We recently shipped the fifth major release, bringing a ton of architectural improvements and new capabilities. In this article, we’ll take a deep dive into the highlights of version 5.0.0 and explain why you should plan your upgrade as soon as possible.

Fresh Minimum: Angular 19+

In this new major version of our libraries, we raised the minimum supported Angular version to 19 and above. This means we can take advantage of all the new features and improvements added since Angular 16 (the minimum supported version in the previous Taiga UI major). And the paradigm shift toward a signal-based style has changed a lot in our codebase.

Signal Inputs

All our hundreds of components and directives said goodbye to classic properties decorated with @Input() and switched to their signal-based counterpart — input. Previously, our code had a lot of getters that internally used a private class method decorated with @tuiPure for memoization. Here's a simplified example of that approach:

@Input({required: true})
fileName: string;

// Used in the template
// (potentially recalculated on every re-render)
get type(): string {
   return this.getType(this.file);
}

@tuiPure
private getType(file: string): string {
   const dot = file.lastIndexOf('.');

   return dot > 0 ? file.slice(dot) : '';
}

Now, with signal-based computed, getters are no longer needed, and we can write cleaner, more readable code without extra optimizations. computed takes care of memoization automatically.

file = input.required<string>();

type = computed(() => {
   const dot = file.name.lastIndexOf('.');

   return dot > 0 ? file.name.slice(dot) : '';
});

We’re sending the @tuiPure decorator off into honorable retirement: you were a good friend and helper for many years — thank you!

Signal viewChild(-ren) / contentChild(-ren)

In Taiga components, we frequently used the @ViewChild(‑ren) and @ContentChild(‑ren) decorators. You decorate a property in a component — and the requested DOM element, directive or provider gets automatically assigned to it. A significant limitation of this approach was that these elements only became available in the AfterViewInit and AfterContentInit lifecycle hooks. As a result, constructs like this could pop up in our codebase:

@Component(...)
export class AnyComponent {
   private contentReady$ = new ReplaySubject<boolean>(1);

   children$ = this.contentReady$.pipe(
       switchMap(() => this.childrenQuery.changes),
   )

   @ContentChildren('ref')
   childrenQuery!: QueryList<any>;

   ngAfterContentInit() {
       this.contentReady$.next(true);
   }
}

The contentReady$ stream notifies all its observers that it's safe to proceed. The trick of creating such a stream made the code slightly more declarative compared to directly manipulating all observers inside a hook. But it still produced its fair share of boilerplate.

Signal-based viewChild(-ren) and contentChild(-ren) are a real game-changer. You can practically forget about the AfterViewInit and AfterContentInit hooks, because signals created via viewChild and contentChild know when to update on their own, and all their subscribers automatically recalculate reactively. All those lines from the old approach are replaced by a single built-in one-liner.

Signals Over RxJS

Even though our team deeply respects RxJS and is confident it’ll be around for a long time, we genuinely fell in love with signals. We decided to make them the priority in our public API — not just because of their growing popularity in the Angular community, but because for many reactive tasks they’re a much better fit than RxJS, letting us provide better support and write more optimal, understandable code.

Here are just a few examples of changes from the new major version — the updated TUI_NUMBER_FORMAT and TUI_DATE_FORMAT.

// Before
inject(TUI_NUMBER_FORMAT) // Observable<TuiNumberFormatSettings>
inject(TUI_DATE_FORMAT) // Observable<TuiDateFormatSettings>

// After 
inject(TUI_NUMBER_FORMAT) // Signal<TuiNumberFormatSettings>
inject(TUI_DATE_FORMAT) // Signal<TuiDateFormatSettings>

To sum up the thought about the dawn of the “signal era” in the Taiga codebase: we don’t resist the new trends set by the Angular team. And most importantly, we don’t prevent our users from seamlessly harnessing the full power of signals when building applications with Taiga UI!

We’ve already seen the benefits of the signal-based style firsthand. Less boilerplate, better performance, dramatically fewer Change Detection bugs, and improved support for Zoneless applications!

New Esbuild + Vite Build Engine

Another important change driven by raising the minimum Angular version is the switch to the modern Esbuild + Vite build engine. This move not only improved our own Developer Experience (build time during local development was significantly reduced), but also allowed us to catch bugs in YOUR Esbuild applications (the default for all new Angular apps) before we even release our libraries.

And these aren’t just words — we’ve already fixed several esbuild incompatibility bugs related to circular dependencies (#12435 and #12438), as well as CSS selector specificity issues (#12544, #12543, #12553).

Control Flow

Before Control Flow appeared, the Taiga UI team had already been publishing the structural directive *tuiLet for many years, which allowed you to declare a local variable in a template. The local variable declaration approach was extremely popular. It has now been replaced by the new built-in @let syntax.

The Taiga *tuiLet directive is now gracefully retiring, making way for the built-in @let syntax — which, as a nice bonus, requires zero imports!

Shiny New Component Showcase

We’ve significantly reworked the design and content of our documentation. It now features improved navigation and a more intuitive interface.

I’d also like to remind you that the engine behind our documentation is a reusable solution published as the npm package @taiga-ui/addon-doc. It’s already actively used not only for Taiga UI docs, but also in other Taiga Family products: Maskito, Taiga Editor, Ng Morph, and Ng Draw Flow. This package keeps evolving and gaining new features (for example, a brand-new Table of Contents component was added in this release). You can always use @taiga-ui/addon-doc to build documentation for your own library!

Browser Bump

Here’s a little secret: the favorite part of every major release for Taiga UI maintainers is bumping the minimum supported browser versions. It unlocks new capabilities and features that we happily use in our libraries to write even cleaner and more reliable code.

Already in Taiga UI v4, we set a course for adding RTL support to our libraries. That’s right — we expanded our audience to include Middle Eastern and Central Asian products! With the new browser support, we got access to an even wider list of logical CSS properties, such as inset, padding-inline, margin-inline, and many others.

RTL support has become even easier to maintain, and the code is more robust (since it’s now handled by native logical CSS properties instead of our old fallbacks and workarounds).

We also got access to BigInt. It feels nice to finally have access to all JavaScript data types — at least by 2026! :D We immediately put this to use and added BigInt support to our @maskito/kit library in the Number mask and in our Taiga InputNumber component.

Angular Animations — Goodbye!

Starting with Angular 20.2, the @angular/animations package has been marked as deprecated. And the official Angular documentation now reads as follows:

You can replace all animations based on @angular/animations with plain CSS or JS animation libraries. Removing @angular/animations from your application can significantly reduce the size of your JavaScript bundle. Native CSS animations generally offer superior performance, as they can benefit from hardware acceleration.

And we responded promptly. In Taiga UI v5, we completely dropped the @angular/animations package: all existing animations have been rewritten using pure native CSS, and @angular/animations has been entirely removed from the dependency list of our packages! No more mandatory provideAnimations() just to get Taiga UI up and running.

The trickiest part was natively rewriting the logic around the former :leave mechanism. Currently, there’s no convenient CSS alternative for animating an element leaving the DOM without timers and boilerplate code. But my colleague found an elegant solution to this problem as well. The @taiga-ui/cdk library got a new Animated directive. Just slap this directive on any DOM element — when it appears or disappears, the element gets a CSS class tui-enter / tui-leave, and you can define any CSS animations for that class. All without code boilerplate and in the true Angular way!

It’s also great that we’re moving in the same direction as the Angular team. The Animated directive neatly anticipated the future syntax that the Angular team introduced very recently in their v21 announcement — animate.enter and animate.leave. Migrating from our solution to the built-in Angular syntax will be as simple as it gets — just replace the tuiAnimated directive on an element with animate.enter="tui-enter" and animate.leave="tui-leave" (and keep the CSS files unchanged).

A nice bonus: our Animated directive has been cherry-picked into the fourth major version of Taiga, so you can start gradually moving away from Angular animations in your app right now — even before you begin upgrading your Taiga UI version, and even if your app's Angular version is significantly older than 20.2. And when you upgrade Taiga to v5, @angular/animations will simply disappear from your node_modules.

Simplified Taiga UI Setup for Your Project

Inspired by the modern Angular naming conventions for DI utility functions (provideRouter, provideServerRendering, provideZoneChangeDetection, etc.), we decided to simplify the process of adding Taiga UI to your project. Now, to set up the DI tree, all you need is a single call to provideTaiga(), which automatically provides all the necessary dependencies and initial configurations for our components to work.

For you, it’s just one function call, but under the hood it takes care of automatic font scaling, dark/light theme setup, and other internal configurations needed for Taiga UI components to function correctly!

New Text Fields Are Now a Stable API

We kicked off the large-scale text field refactoring back in the previous major version. At that time, we moved all our old control versions into the @taiga-ui/legacy package (to ensure a smooth migration path for users to the new public API) and started rewriting each component from scratch using fresh design specs and modern Angular features (decomposition via host directives + signals).

The task turned out to be quite challenging and extremely labor-intensive, but the results will genuinely make you happy. The new text fields offer a declarative way to customize through HTML markup and a uniform public API across all types of controls. Once you understand the customization concepts for one type of text field, you can easily customize any other control — without even looking at the docs!

Another key feature of the new text fields is their openness. Everything you need is exposed, so you can bring even the wildest ideas to life. Just take a look at this InputDate example:

<tui-textfield>
  <label tuiLabel>Choose a date</label>
  <input tuiInputDate [formControl]="control" />

  <ng-container *tuiDropdown>
    <tui-calendar [markerHandler]="markerHandler" />

    <button
      tuiButton
      (click)="..."
    >
      Today
    </button>
  </ng-container>
</tui-textfield>

First, all the input parameters of the <tui-calendar /> component are fully at our disposal — no prop drilling like in the previous version of this control! Second, we can freely add any elements (even interactive ones!) to the calendar dropdown — for example, a "Today" button with a custom click handler!

And this applies to every type of text field (and there are over 15 of them!). With the release of the fifth major version, our large-scale text field refactoring is officially complete. Their public API is fully stabilized, and the previous generation of these controls has been permanently removed from the @taiga-ui/legacy package.

For those who prefer gradual changes in life and code, we cherry-picked all important fixes for the new text fields into the fourth major version, making the migration to the new major as smooth as possible. Before upgrading to Taiga v5, you can iteratively update your codebase, mixing old and new text fields, so the upcoming migration is as comfortable and painless as it can be.

Improved Icon Component

In the previous major release announcement, I mentioned that for icons we moved away from the old approach of using <svg /> with the <use /> tag in favor of CSS masks.

Back then, the new approach was implemented in the Icon component and brought numerous benefits: the ability to store icons on a CDN and render them without DOM manipulations or a sanitizer, automatic browser caching, and a simplified way to scale icons.

But we didn’t stop there and continued to develop this further. Starting with the fifth major version, this component can do significantly more:

• You can now control not only the icon size but also the stroke width of the icon’s content. This capability is demonstrated really well in this interactive documentation example.
• The updated component supports not only classic single-color icons but also multi-color and font-based icons! They’re managed through the @tui, @img, and @font prefixes, and the component figures out under the hood how to render the icon based on its type: via CSS mask, background-image, or font + content on the :before pseudo-element. You can see it in action in this example.

And Much More!

• Portals have been completely rewritten and streamlined into a single grid-based container. It’s now even easier to customize dialogs, simpler to manage notifications and their subtypes (screen position, number of simultaneous instances), and easier to create your own custom portal entities through new abstract classes and services.
• A new Popout service that simplifies displaying custom content in Picture-in-Picture mode or opening a piece of your application in an entirely new tab.
• We stabilized the use of the CloseWatcher web API in Taiga dialogs. Now, when a dialog is open on an Android device and the user taps the browser’s “Back” button, the dialog simply closes — instead of navigating to the previous route behind the open dialog.
• A revamped Accordion. We’re continuing the trend (that accompanies every Taiga major version) of minimal DOM element nesting in our components, which should make it easier for you to customize them and set native attributes like ARIA attributes or id — and now the accordion has joined the ranks of the “lucky ones.”
• Automatic font scaling is now enabled by default. Many users rely on iOS/Android system accessibility settings to increase the font size across all interfaces on their mobile devices — including web apps. Taiga components can read this system setting and adapt, making your interfaces comfortable for users with visual impairments.
• We dropped the use of our custom decorators — you’re free to build your application with any value of the TypeScript experimentalDecorators flag without worrying that Taiga UI components will stop working.
• We’re continuing to actively develop AI tooling support for working with Taiga UI components. Our MCP server now supports the new major version as well. We’re also closely watching the development of WebMCP to integrate its support into our documentation when the time comes.

And a huge number of other improvements and new features that you can find in the release notes.

How to Upgrade?

We did our best to make the migration to the new version as smooth as possible. To that end, we’ve prepared a bunch of migration scripts that will automatically analyze your code and fix most breaking changes — all with a single console command! And anything that was too complex to fix automatically via AST manipulations has been annotated with comments right in the code — complete with hints and links so you can easily finish the migration on your own or with the help of AI agents.

Detailed instructions for running the migration schematics and the necessary preparation steps are available in our upgrade guide.

If you run into any issues or bugs during the upgrade, don’t hesitate to open an issue or ask a question in our Telegram community. The Taiga team can’t wait for your feedback!

See You Soon!

To wrap up, let me just give you a little sneak peek at our future plans.

Very soon you’ll see revamped date picker components — our design team has already delivered fresh design specs with a more modern look for the calendars. During the rework, we plan to address the accumulated feature requests around their customization.

We’re also keeping a close eye on the development of signal-based forms. As of this writing, the new API is still rough around the edges and continues to undergo changes. As soon as it fully stabilizes, we’ll make sure Taiga controls support them.

Finally, one of our big goals for this year is to keep pushing the accessibility of our components forward! All Taiga components traditionally support keyboard navigation but accessibility is a broader topic and we plan to dedicate even more attention to it this year.

See you in upcoming articles and releases!

And a reminder: the easiest way to say thank you is to give us a star on GitHub.

What’s New in Taiga UI v5: A Modern Angular UI Kit was originally published in AngularWave on Medium, where people are continuing the conversation by highlighting and responding to this story.

CSS magic

Of course, how would we do without it? First, we need to hide native scrollbars. We can do this in every browser these days.

There is a standard rule scrollbar-width, which only Firefox support at the moment. For older Edge and IE version there’s similar -ms-overflow-style. We will not support IE though, because we are going to need position: sticky. Chrome and Safari can use ::-webkit-scrollbar pseudo selector.

Second, to keep native scrolling behavior we need to have our component be scrollable container itself. This means instead of a scrolling wrapper we must come up with some sort of local position: fixed for thumbs. Absolute position will not work because thumbs would scroll with content.

We can achieve this with a clever combination of position: sticky for thumbs and display: flex for component. We are going to need two containers inside:

We will begin by isolating stacking context.

Not everybody knows about stacking context, that’s why you can often run into z-index war with values like 1000, 1001, 9999. I encourage you to educate yourself in this subject, it would help you a ton!

To keep everything inside content from overlapping the thumbs we would add the following style to the wrapper: position: relative, z-index: 0. It creates new stacking context and nothing from within would be able to overlap elements hanging above outside.

Bars need z-index: 1, to move them above content and a minimum width of 100%. Now we have the following picture:

Bars have taken up all the space, shifting content to the right. Scrolling works fine and bars behave as if they were fixed inside component. Now we need to add margin-right: -100%, and they would «make room» for all the content.

We can achieve this without flex using floats but bars wrapper will not be able to take up whole height if it is set implicitly (max-height, flex: 1 and so on).

Angular

If you have read my other articles you know that I’m a huge declarative approach evangelist. This time won’t be an exception. Our code will be tidy as usual. We will only implement vertical scroll, horizontal is exactly the same. Let’s add thumb to the template:

We position it with getters:

Now all we need is to listen to scroll events to trigger change detection — our component works with wheel or trackpad. But we need to be able to drag thumbs. This logic is better suited for a directive. However, to keep everything transparent we will have it in our component for this tutorial.

Dragging starts with mousedown event on a thumb, continues with mousemove on the document and ends with mouseup on the document.

Let’s add event handlers on the thumb:

Inside component we add handlers that compute scroll position and listen to mouseup:

Now thumbs dragging works too.

Angular magic

Seasoned Angular developer might have noticed that this solution has very bad performance. For every instance of a scrollbar we listen to all mousemove events on the whole document and trigger change detection on every single one of them. This won’t do. Thankfully, Angular provides a way to manage event handling which I wrote about before. With @tinkoff/ng-event-plugins library we can get rid of unnecessary change detection runs. To do so we will add a modifier .silent to the event name and @shouldCall decorator to the handler:

Until Angular 10 we have to couple @shouldCall with @HostListener(‘init.xxx’, [‘$event’]). We need this to trigger change detection, while markDirty is private. Read about it in detail in aforementioned article.

To check if we need to call the handler we can use this simple function:

Now event handlers and change detection will be triggered only if we are dragging the thumb. Our scrollbar is ready to use. Full scrollbar demo is available on Stackblitz.

Directive

As I said before, we can isolate drag logic into directive. Originally I was happy with what we had, but comments from colleagues got me thinking. It would make our code more declarative and simple. We can even get away with just one Output made of single RxJs chain using fromEvent. I will not go into details here, just look at the code:

Calculations we moved to separate functions, full code is available on updated Stackblitz here.

As an improvement, we can also watch for component resize to recalculate thumbs size and position. It’s a great case for a ResizeObserver which you can use in Angular with ease if you read this article. Or head straight to our library @ng-web-apis/resize-observer.

Custom scrollbar in Angular was originally published in AngularWave on Medium, where people are continuing the conversation by highlighting and responding to this story.

To safely inline SVGs you need to sanitize them. Built-in Angular sanitizer, for example, does not support SVGs. It clears them into empty strings. You can use DOMPurify as a trusted solution and our library ng-dompurify if you need it in an Angular app.

Let’s look at another option available in modern browsers — SVG tag USE.

What use is USE to us?

This tag is intended for reusing symbols and entire SVGs across the document. But in modern browsers (sorry IE) it can even reach for external sources!

External SVGs must be on the same origin, so CDNs will not work, unfortunately. Yet.

This provides a native way to inline SVGs in Shadow DOM, kinda like IMG tag with src, but also styleable with CSS. And it works with cache too! We need to prepare our icons a little bit though, let’s see what we need to do.

First, we have to create a symbol in each icon and move viewBox data in it.

Next, we need to set fill (or stroke) color to currentColor so we can then use CSS color to control it. We can also set SVG rules like fill and stroke on other elements to inherit. It would allow us to have multicolor icons, see example below.

Once our icons are prepared we can dump them in our assets folder and use them!

Named icons component for Angular

Writing full path and reaching for symbol every time is tedious. Let’s create an Angular component that would work with icons by their names. With Dependency Injection it is very easy.

We need a token to provide a path to all our icons and a simple component. It would resolve href based on the name and given path. We can even target native SVG with selector. This way we do not need to control size on component’s side.

Keep in mind that Safari below 12.1 only supports deprecated xlink:href so it’s better to have both.

We will have stroke and fill transparent. This allows us to control multiple colors with CSS.

Let’s give our component a shot:

Conclusion

This approach’s limitations are no IE support and same origin rule. If you can live with these it might be an easy alternative to other solutions. You do not have to bundle your icons in your app or manually load them. You can rely on cache to speed things up and no DOM operations makes it much faster than inlining full icons. Happy coloring!

Natively colored SVG icons was originally published in AngularWave on Medium, where people are continuing the conversation by highlighting and responding to this story.

1. Know how change detection works in Angular

There are many great articles going deep into change detection mechanism. Like this one. So let’s just recap the basics quickly and get to the tips.

Recap

Angular has two change detection modes: Default and OnPush. First one triggers change detection for every tick happened anywhere in the app. Second only marks view for checking if an event has happened in this view or if input data has changed.

Default vs OnPush

There’s really no reason for you to use Default. All you need to do is write your code the way framework expects it to and you won’t get into trouble with OnPush. This means, you should never mutate your data. If your input arrays or objects change immutably, OnPush would pick this up and refresh the view.

When you subscribe to events with @HostListener Angular has got you covered as well. But what if you are working with RxJS streams? You can always inject ChangeDetectorRef and do markForCheck() when you need it. But a declarative option would be to end up with async pipe in your template. It would trigger change detection on each emit.

You might have seen this pattern:

<div *ngIf="stream$ | async as result">
  ...
</div>

But what do you do when you need falsy results too? You can strip condition logic from ngIf and create a simple structural directive. It would be used only to add context to the view:

💡#AngularTip for the day! Like declaring async results with *ngIf="stream$ | async as result" but need to support falsy values? Here's a simple #angular directive that does just that! 👍https://t.co/4DR9pdZsIc pic.twitter.com/E9rjPwnnAn

NgZone

If you cannot fully switch to OnPush there are still things you could optimize. You can inject NgZone and do performance sensitive actions in .runOutsideAngular(). This way there will be no extra ticks in the change detection mechanism. Even components with Default strategy will not perform change detection cycle. You should do this for events that trigger rapidly like mousemove, scroll. To do it declaratively with RxJS streams you can create two operators. One for leaving the zone and another to return to it if you need to trigger change detection:

💡#AngularTip for the day! Manage NgZone in your #RxJS streams to avoid extra ticks in you #Angular app with these 2 simple operators🧑‍💻Code: https://t.co/GwoCJYLTYp pic.twitter.com/1SdcJQrwQl

Another option you can have with @HostListener decorator is custom event manager plugin. We released an open-source library called ng-event-plugins. It allows you to filter out unnecessary change detection cycles. Read more about it in this article.

2. Learn RxJS. Seriously!

RxJS is a very powerful tool. We all use it to some extent when working with Angular but really mastering it can help you a lot. From very simple streams that allow you to reload your component…

💡#AngularTip for the day! Create a simple #RxJS stream to quickly reload your #Angular component♻️ pic.twitter.com/e7OaTNgL2A

…to complex operators combination. Like this example recognizing various types of scroll:

💡#AngularTip for the day! Learn how to differentiate regular scroll from momentum scroll in your #Angular app on mobile with #RxJS📱Live demo: https://t.co/5egs6gXexp pic.twitter.com/3eQQcWCzg5

Just take a look how easy it is to create a sticky header that disappears when you scroll down. A little bit of CSS and pretty basic RxJS:

💡#AngularTip for the day! Create an #Angular directive for sticky header that disappears when you scroll down👍Live demo:https://t.co/wli6vAnf9GWINDOW token from our library:https://t.co/kgfN68QtIyUnsubscribe with destroy service from this tweet: https://t.co/7fdQgJTFLB pic.twitter.com/Xlc2je9Kny

I cannot stress enough how important RxJS knowledge is to an Angular developer long term. While it’s simple on the first look, RxJS requires a little bit of paradigm shift. You need to start thinking in terms of streams. But once you do, your code would become more declarative and easier to maintain.

There is not much I can suggest here other than practice. If you see a case that you can solve with RxJS — try to do so. Avoid side-effects and nested subscribes. Keep your streams organized and watch out for memory leaks (read further).

3. Max out TypeScript

We all use TypeScript in our Angular applications. But to get the most of it we need to push it to the limits. I rarely see projects with enabled strict: true. This is something you totally should do. It will save you from lots of cannot read property of nulls and undefined is not a functions.

Generics

In TypeScript we can use generics when the type we work with is unclear. Combination of generics, overloads and type narrowing can make a pretty solid API. You almost never will have to typecast. Take a look at this example of strongly typed RxJS method fromEvent:

💡#AngularTip for the day! Tired of typecasting event target or defining event type for #RxJS method 'fromEvent'? Add custom type and a typed wrapper function!🎯Live example: https://t.co/Uo003HLZ0x#Angular #TypeScript #100DaysOfCode #developer pic.twitter.com/CbdQj424I3

With it you can be sure that target in the event has the same type as the element you listen the event on. And event has properly narrowed type.

Generics based APIs have the benefit of being data-model agnostic. This means people can use it without being forced to a particular interface

There are articles dealing with things like type inference, advanced types, unions. I suggest you educate yourself in the subject, it would help you make robust code in the long run. My one last advice here is never use any. You can almost always replace it with generic or unknown which is a safer version of any.

Decorators

Don’t forget about other TypeScript features, such as decorators. When used well, they can really improve your code. There are cases when type is correct, but logically value is unacceptable. Like when you have a number input for quantity — you cannot really have negative or decimal values. But according to TypeScript they are correct. You can protect your components for such invalid inputs with assertion decorator:

💡#AngularTip for the day! Protect your #angular components from illegal but properly typed inputs with assertion #TypeScript decorator🦺Code: https://t.co/8P4SANVnjx pic.twitter.com/pwJVGgFevt

Did you know that if you decorate your abstract classes you do not have to pass arguments to super()? Angular will handle it for you:

💡#AngularTip for the day! If you decorate your abstract class, #Angular will resolve constructor parameters and you do not need to add constructor to concrete implementation!🏗️ pic.twitter.com/hUwz671iPF

Another good case for custom decorator is some reusable processing logic. For example, in our Web Audio API library for Angular we turn declarative input bindings to imperative native commands with a strongly typed decorator:

ng-web-apis/audio

You can read about this library in detail here

4. Angular’s DI is king! Use it. Then use it more!

Dependency Injection is part of the reason Angular is such a powerful framework. Arguably it is THE reason. Too often it is not used to its full potential.

Head over to this dedicated article about DI we wrote to deepen you knowledge about it

RxJS

When it comes to practical advises, I mentioned before to watch out for memory leaks in your RxJS streams. Mainly this means: if you manually subscribe to a stream you need to unsubscribe yourself. An idiomatic solution in Angular would be to encapsulate this logic into a service:

💡#AngularTip for the day! Create a simple #RxJs Observable service to encapsulate destruction logic of your #Angular components and directives🔧 pic.twitter.com/iD8uLvl9x3

You can also create shared streams and add them to DI tree. There’s no reason to have separate requestAnimationFrame based Observables across the app. Create a token for it and reuse. You can also add zone operators discussed above to it:

💡#AngularTip for the day! Create a shared requestAnimationFrame-based #RxJS Observable to use across your #Angular app⏱️ℹ️ or just use our opensource library of tokens for native APIs: https://t.co/kgfN6984A6 pic.twitter.com/Drj7YL9RHd

Tokens

DI is also a good way to make your components more abstract. If you do not rely on global objects, such as window or navigator — you are ready for Angular Universal which renders you app on the server side. As you know, node.js does not have DOM and many of the global objects we are used to. It is also much easier to test such code because dependencies are effortlessly mocked. It is not difficult at all to tokenize these objects. We can use factories when we define injection token and top level injector is available to us. Using built-in DOCUMENT it takes just a few lines to create WINDOW token:

💡#AngularTip for the day! You can use 'inject' method from '@angular / core' in the context of a factory function to reach for type-safe dependencies for #angular injectable. Here's how easy it is to tokenize global window!💪Read more: https://t.co/abP7GNgsie pic.twitter.com/5Y7eVBX2xg

To save time, use this open-source library where we already created some of those tokens. There’s also its Angular Universal counterpart with mocks. Feel free to request other tokens to be added!

Tokens and factories are very powerful tools. Combined with hierarchical nature of dependency injection they can help you make your app very modular. Read more about clever use of providers in this article.

5. Throw emperor down the abyss. Like Vader.

Angular with its template bindings and decorators clearly pushes us to write declarative code. I’ve mentioned this approach above. I will not get into discussion of benefits it has over imperative code here. Instead I’ll give you a solid advice: write declarative code. When you get used to it, you’d appreciate it.

Getters

What does it mean to write declarative code? First of all, try to use ngOnChanges as rare as you can. It’s a poorly typed side-effect which is really only needed if you must perform an action upon multiple inputs change. On a single one a setter is a more streamlined solution. And if instead of action you wanted to update some internal state, think if you can remove that manual state and replace it with calculated getter.

Performance and getters is a subject for a separate article which I hope to get to writing soon. For now, just take a rule of thumb to not create new arrays or objects in getters. If you need to calculate a new object, use memoization techniques like pipes, for example.

💡#AngularTip for the day! Sparkle come #CSS variables magic over your #Angular app and create isolated themes with 1 line of code!🎨Live demo: https://t.co/Brm3Lr4Zq6🚨Be careful though! Angular style binding does not sanitize content! pic.twitter.com/MzZkxmprFY

Here’s a good case for a setter which I’ve omitted for the brevity of the example (but was reminded of by an attentive follower).

Template reference variables

Instead of manually requesting elements for the view, Angular has @ViewChild decorator. Quite often though, you don’t really need it if you can enclose logic in the template:

<input #input>
<button (click)="onClick(input)">Focus</button>

Here we pass template reference variable directly to the method where we need it. This makes our component code clear. Think of it as sort of a closure in a template. But what do we do if we need a DOM element of an underlying component? We could have @ViewChild(MyComponent, {read: ElementRef} but we can do this without decorator if we create a directive with exportAs:

💡#AngularTip for the day! Ever needed to get #HTML element behind your #Angular component with a template reference variable? Write a simple directive to expose it!🔍 pic.twitter.com/XfFtcQsGXT

Dynamic content

People often use ComponentFactoryResolver to create dynamic components imperatively. Why, if there is ngComponentOutlet directive? Because this way you have access to the instance and can pass some data to it. A proper way to solve this issue is, once again, dependency injection. ngComponentOutlet allows you to pass custom Injector which you can create with data provided through token.

In fact, to create dynamic content you have interpolation, templates and components. And there is not much difference between these approaches. You have context and your have a representation:

💡#AngularTip for the day! When creating customizable #Angular components, think in terms of content and context, not in terms of templates, functions, literals. Check out my #opensource project that acts as interpolation, template & component outlet!👍https://t.co/piqcF8uujb pic.twitter.com/xINZsRuxjE

I’ve been using this content-agnostic approach to customizable components for a long time. We’ve released a tiny open-source library called ng-polymorpheus. It doesn’t do anything really, just pass content to the proper built-in Angular tool, be it ngTemplateOutlet, ngContentOutlet or simple function interpolation. Once you get used to it, there’s no going back!

This wraps it up for this article. Hope you would find these tips useful!

If you like this, you can check all of our tips. We also wrote an advanced Angular handbook which we continue to develop over at angular.institute. Happy coding!

Bonus

A simple tip that was received unexpectedly well is Luhn algorithm in form of an Angular Validator. So if you are working on some application where users enter their credit card number, you can use this code to check its validity 😉

💡#AngularTip for the day! Create #Angular validator to check validity of entered card number with Luhn algorithm💳 pic.twitter.com/QdPPpCqwdK

5 tips to boost your Angular skills was originally published in AngularWave on Medium, where people are continuing the conversation by highlighting and responding to this story.

From the beginning, it was a responsibility of ControlValueAccessor. Angular has several accessors out of the box: for checkboxes, inputs, selects. Let’s say you develop a chat application. You need to be able to change style of the text. Make it bold or underlined, add emojis and so on. You would most likely use contenteditable attribute to handle formatting.

Angular does not have an accessor for contenteditable, so if you want to use it with forms you will have to write one.

ControlValueAccessor

Directive that we will create is going to react to contenteditable attribute. And it will implement ControlValueAccessor interface:

To support both reactive and template forms we will provide a special InjectionToken:

We need to implement 3 required and 1 optional methods:

• registerOnChange — this method will receive a function during control initialization. Our directive needs to call that function with a new value when user enters something in an editable element. This would propagate value to the control.
• registerOnTouched — this method will receive a function during control initialization. We need to call it when user left our element so control would become touched. It is important for validation.
• writeValue — this method will be called by control to pass value to our directive. It is used to sync value when it is changed externally (setValue or ngModel variable change), and to set initial value.

Worth mentioning that template forms have a bug related to this method. Initial value is provided with a slight delay and writeValue is called twice, first time with null:
https://github.com/angular/angular/issues/14988

• setDisabledState (optional) — this method will be called by control when disabled state is changed. Even though it is optional it is a good idea to have it, otherwise we cannot have our control disabled.

Implementation

To work with DOM element we need Renderer2 and element itself so let’s add them to constructor:

We will store references to the methods control gives us:

disabled for contenteditable is equal to contenteditable="false". Setting value is the same as setting innerHTML for DOM element. Value change and focus loss can be tracked with events:

That’s it. This is enough to make Angular forms work with contenteditable elements.

Internet Explorer

There are couple of “buts”.

First, initial control value is null and after writeValue in IE11 this is what we will see in the template, literal “null” string. To handle this we need to normalize value:

Here we also take care of the following case. Say element had some HTML tags inside. If we just select everything and hit backspace — content gets replaced with a single <br> tag. It’s best to consider it equal to empty string so our control thinks it’s empty.

Second, Internet Explorer does not support input event for contenteditable elements. So we are gonna have to make a fallback with aMutationObserver.

By the way, if you want to use MutationObserver as a declarative Angular directive or an Observable-based service you are welcome to take a look at our little library: https://github.com/ng-web-apis/mutation-observer

Instead of checking the browser we will just turn MutationObserver off on a first input event:

Now our component works in IE11 and we are proud of ourselves!

Internet Explorer! ლ(ಠ益ಠლ)

Unfortunately, IE11 will not let go so easily. Apparently it has a bug in MutationObserver. Say contenteditable has tags, for example some <b>text</b>. Removing text that would cause a whole tag to be removed (word text in this example), observer callback will be triggered before actual changes to the DOM!

Unfortunately, we have to call it a loss and resort to using setTimeout:

Summary

Considering Angular has to support IE9, 10 and 11 we can understand why they did not make such accessor built-in.

We need to remember that HTML can have malicious code placed in it. We shouldn’t blindly add it do the DOM.

And we cannot trust users either so we must watch out for paste and drop events. Such content has to be sanitized. A good and trusted tool for that is DOMPurify. Read here how we implemented it in an Angular app or just download our package:

TinkoffCreditSystems/ng-dompurify

You can also grab the accessor we’ve created in this article as a tiny package that works in Angular 4+:

TinkoffCreditSystems/angular-contenteditable-accessor

A live playground:

ControlValueAccessor and contenteditable in Angular was originally published in AngularWave on Medium, where people are continuing the conversation by highlighting and responding to this story.

When I first heard about compliant mechanisms I was very impressed. Even though they surround us in our daily lives — we barely ever think about what they are conceptually.

These are things like backpack latches, mouse buttons, shampoo caps. In short, a compliant mechanism uses deformation to achieve its technical characteristics. In traditional engineering, flexibility is usually a disadvantage of the material. Compliant mechanisms on the contrary use it to transfer force and movement, instead of passing it through multiple moving parts as rigid body mechanisms do.

In such a system movement is very easy to predict. Because this is a single item, rather than a set of parts with hinges, springs, and joints all contributing to friction, wearing, and backlash.

This precision is understandable. The movement goes through flexible connections that cannot contract or expand. So it’s always auto-corrected and guided by the whole item.

I find it to be a perfect analogy to the declarative approach in programming, as opposed to imperative in which commands manually alter the state. Just like hinges and joints pass force.

I would like to share my view on writing Angular code. It’s sort of a philosophy or habit I developed over the years of working on a big UI library.

Compliant components

Angular always assumes some level of declarative code. Data bindings, event handling, and the Observable model — these all influence our style. Simple components are literally written with statements. We write what is what and how it depends on the environment instead of a set of instructions altering the state. But with increasing complexity, components might lose this quality. They turn into a series of calls, subscriptions, and stored data managing behavior. Syncing all this becomes a struggle.

The imperative approach states “if a car is a firetruck, paint it red”. The declarative way would be “firetrucks are red”. In Angular, this is effectively a getter. In a closer look, often the state for the component is the inputs and the rest is all calculable. To better grasp this idea, let’s create a few components utilizing this approach.

LineChart

This component is pretty straightforward at its core. We provide an array of tuples and we need to make an SVG path over those points on a 2D plane. What we want is to organize the component code so it doesn’t have imperative state manipulation. We can hook it to native SVG to have less nesting:

Besides actual data, we need to outline the area to display. This could be the viewBox itself. But it is much more user friendly to enter its properties separately and calculate it with a getter:

To make our component spicier let’s add smoothing input as well. The template would consist of a single path element:

We need to calculate the d attribute. One option is to have a setter on data input. But later we might want to add other related elements like fill under the line or hints for points. Instead, let’s create it with a getter as well so we will not have to manage it ourselves:

That’s it. The actual draw functions to make the path are irrelevant and can be googled. But read further for a live demo of all the components we are about to create complete with source code.

Media directive

The next thing I’d like to explore is a bit more complex. We want to be able to control media elements such as audio and video tags. And we want to do it with minimal imperative calls. To do so let’s create a directive. There are 3 things to control: current time, volume and play/pause state. They can also be changed through native controls so it’s going to be a two-way binding:

See that @HostBinding on volume? It’s enough to get it working. But when it comes to currentTime — it changes on its own when the media is playing. So such binding would get into a messy loop updating back and forth. Instead, we need to upgrade it to setter and watch for not setting the same value again:

We will also turn paused input to a getter/setter pair:

Making a video player component with such a directive is a breeze:

With ng-content users can provide sources like they would with native video tag. And the code for the player component is shamelessly short:

Combo Box

Now that we’ve got the vibe of declarative programming, let’s get into the meat and grit of things. Combo Box is a much more complex example, but don’t worry! We will not have a single function with more than one line! Well, maybe one.

During this part of the article, I would also rely on declarative preventDefault. It uses the ng-event-plugins library that I wrote about in detail in this article.

First, let’s establish the template. We will not get into creating custom controls for Angular as that is quite another topic. Instead, we will wrap it around a native input to allow users full control over it:

The inner template will use a label to focus the input when the user clicks on the arrow. Yes, this technique is a bit dirty. Users will not be able to add an accessible label by simply wrapping our component. But, it suffices for the sake of simplicity this time.

Preventing default on mousedown events is necessary so focus never leaves the input. This component has a single @Input — an array of strings as suggestions. And this time it would have a single internal state we would manage. You might think it’s open property to show the dropdown but it’s not. It’s a currently focused suggestion index in the dropdown. We would leverage NaN as an indicator for no selected item to stick within the number type. And open is a getter to see if there is a suggestion currently selected:

We need to narrow suggestions to those that fit the user input. We can add NgControl as @ContentChild and access its value. We will then use it to filter the given array:

Now we can add another getter for the currently selected index. We will clamp it to the length of the filtered suggestion:

This new getter is safe to use as it will always be within the limit of available items. Now let’s add the event handlers we had in the template. We need to toggle dropdown on an arrow click, select an item from the list, and update the current index on hover:

Next we need to handle keyboard navigation. It consists of using arrows to open dropdown and pick suggestions with the enter key. And also show the list as the user types:

And that pretty much sums it up. This component is now fully operational. We wrote it in a declarative fashion only keeping track of a single state ourselves. We don’t have imperative commands like “open dropdown”. Instead we described the behavior of our component, relative to its states: control value, an input list of suggestions and a currently active one. That’s why it is called a declarative approach.

In reality you would also want to make it accessible. You can add ARIA attributes such as aria-activedescendant. This way screen readers and other assistive technologies also keep track of the selected suggestion. Read more about the combobox pattern here and here.

Ever wondered why AK-47 is such a prominent weapon of the past decades? Its construction only has 8 moving parts. This makes it easy to manufacture, operate and maintain. Same applies to software architecture. The less states you have to manage, the more robust your code is. Simple design is a reliable design. And while declarative code might not seem simple at first glance — once you get used to it, you will appreciate its neatness.

Performance

A natural question that arises — if we keep recalculating, wouldn’t performance suffer? Of course, the OnPush change detection strategy is a must. And frankly, I have never seen a case where the Default strategy was justified. Except for a field error component. As Angular forms still do not have a touched stream at the time of this writing.

To assess performance we need to pay attention to what we do in our getters. A string concatenation like we had with viewBox has a speed of about 1 billion operations per second. 300 millions on a mediocre Android phone. So it’s not a concern. Same goes for simple math operations. Things get interesting when we get to arrays and objects. Iterating over 100 items array to find an item takes 15 million ops/sec on PC and is ten times slower on a smartphone. Immutable operations that create new instances of arrays are even more taxing. Filtering a 100 items array is about 3 million ops/sec on PC and humble 300k on an Android device. Working with immutable objects is similar due to underlying JavaScript mechanics. You can check performance yourself here. This means to make compliant components a thing we need to optimize them.

Let’s add a simple memoization technique so we do not do unnecessary recalculations. We can create a decorator for pure methods. It would remember passed arguments and the last result. If arguments stayed the same — it would return the result it remembers.

This way we can refactor our code to the following pattern on a getter and a pure method couples:

Let’s benchmark our approach. We will test against plain declarative approach and imperative updates with ngOnChanges:

In this StackBlitz we have a list of 1000 components and a button to trigger change detection in all of them. You can select imperative which is effectively a dry run. Inputs do not change and nothing is happening on a change detection cycle. Declarative components have several getters. A logical one to check if a value is bigger than threshold. A string concatenation. A math getter with @HostBinding to a class. An array iterator. An array generator and an object generator. Keep in mind that all this is multiplied by 1000 because this is what each component has. And the last column has @Pure decorator on array and object operations. Here are the results averaging over a 100 change detection runs for each column:

Here are results on a smartphone:

Difference on a PC is within the margin of error while on a medium-tier Android device it is about 10%. One can look at it and say it’s 10% slower. But there’s another way to look at it. Even on the weak machine with several thousands of getters at the same run it stays within a single 60FPS frame. And it is only 1.5 milliseconds slower than basically nothing — a dry run by Angular. Typically, the real performance hog is DOM manipulations. They are the heaviest operations of an average app. Remember class binding with a getter from above benchmark? Great thing about browsers is they do not alter DOM if value stays the same, be it class binding, style or attribute. You should organize your view tree properly, use memoization techniques and OnPush. This way declarative approach will not be a performance bottleneck.

Summary

Components written this way are robust and flexible. They might require a little bit of a paradigm shift to get used to. But once you start thinking like this, you will see what a pleasure it is to write and maintain such code. It does take attention from you to watch out for pitfalls. Otherwise performance would suffer. But from my experience it’s so worth it, it has changed my overall attitude towards the front-end. I’ve added a new chapter to our paid advanced Angular handbook over at angular.institute. It expands upon this concept with practical tips and tricks, head over there if you want to learn more. Described examples can be played with here:

I work as the lead developer of a proprietary UI kit at Tinkoff. The whole library is built on principles outlined here. Right now, it is in the process of being open-sourced. A foundation package already available on GitHub and npm. It has that pure decorator and a lot of other neat low level tools to help you build awesome Angular applications. We will sure cover those in upcoming articles so stay tuned for more!

Compliant components: Declarative approach in Angular was originally published in AngularWave on Medium, where people are continuing the conversation by highlighting and responding to this story.

Web Audio API has been around for a while now and there are lots of great articles about it. So I will not go into details regarding the API. What I will tell you is Web Audio can be Angular’s best friend if you introduce it well. So let’s do this.

Basics

In Web Audio API you create a graph of audio nodes that process the sound passing through them. They can change volume, introduce delay or distort the signal. Browsers have special AudioNodes with various parameters to handle this. Initially, one would create them with factory functions of AudioContext:

But since then they became proper constructors which means you can extend them. This allows us to elegantly and declaratively use Web Audio API in Angular.

Directives

Angular directives are classes and they can extend existing native classes. Typical feedback loop to create echo effect with Web Audio looks like this:

We can see that vanilla code is purely imperative. We create objects, set parameters, manually assemble the graph using connect method. In the example above we use HTML audio tag. When user presses play he would hear echo on his audio file. We will replicate this case using directives. AudioContext will be delivered through Dependency Injection.

Both GainNode and DelayNode have only one parameter each — gain and delay time. That is not just a number, it is an AudioParam. We will see what that means a bit later.

Note that all AudioNodes have 3 parameters: channelCount, channelCountMode and channelInterpretation. Thanks to inputs property from @Directive decorator we can just list them and they would work properly without a single line of code.

To declaratively link our nodes into graph we will add AUDIO_NODE token. All our directives will provide it.

Directives take closest node from DI and connect with it. We’ve also added exportAs — it allows us to grab node with template reference variables. Now we can build graph with template:

We will end a branch and direct sound to the speakers with waAudioDestinationNode:

To be able to create loops like in the echo example above Dependency Injection is not enough. We will make a special directive. It would allow us to pass node as input to connect to it:

Both those directives extend GainNode which creates an extra node in the graph. It allows us to disconnect it in ngOnDestroy easily. We do not need to remember everything that is connected to our directive. We can just disconnect this from everything at once.

Source nodes

The last directive we need to complete our example is a bit different. It’s a source node and it’s always at the top of our graph. We will put a directive on audio tag and it will turn it into MediaElementAudioSourceNode for us:

Now let’s create the echo example with our directives:

There are lots of different nodes in Web Audio API but all of them can be implemented using similar approach. Two other important source nodes are OscillatorNode and AudioBufferSourceNode. Often we do not want to add anything into DOM. And there is no need to provide audio file controls to the user. In that case AudioBufferSourceNode is a better option than audio tag. Only inconvenience is — it works with AudioBuffer unlike audio tag which takes a link to an audio asset. We can create a service to mitigate that:

Now we can create a directive that works both with AudioBuffer and audio asset URL:

Worth mentioning that we also added autoplay attribute like one in audio tag so that sound can start playing immediately.

AudioParam

Audio nodes have a special kind of properties — AudioParam. For example gain in GainNode. That's why we used setter for it. Such property value can be automated. You can set it to change linearly, exponentially or even over an array of values in a given time. We need some sort of handler which would allow us to take care of this for all such inputs of our directives. Decorator is a good option for this case:

Decorator would pass processing to a dedicated function:

Strong types will not allow us to accidentally use it for a non-existent parameter. So what would AudioParamInput type look like? Besides number it would include an automation object:

processAudioParam function translates those objects into native API commands. It's pretty boring so I will just describe the principle. If current value is 0 and we want it to linearly change to 1 in a second we would pass {value: 1, duration: 1, mode: ‘linear’}. For complex automation we would also need to support an array of such objects.

We would typically pass an automation object with short duration instead of plane number. It prevents audible clicking artifacts when parameter changes abruptly. But it's not convenient to do it manually all the time. Let's create a pipe that would take target value, duration and optional mode as arguments:

Besides, AudioParam can be automated by connecting an oscillator to it. Usually a frequency lower than 1 is used and it is called an LFO — Low Frequency Oscillator. It can create movement in sound. In example below it adds texture to otherwise static chords. It modulates frequency of a filter they pass through. To connect oscillator to a parameter we can use our waOutput directive. We can access node thanks to exportAs:

Retrowave time

Web Audio API can be used for different things. From real time processing of a voice for a podcast to math computations, Fourier transforms and more. Let’s compose a short music piece using our directives:

We will start with simple task — straight drum beat. To count beats we will create a stream and add it to DI:

We have 4 beats per measure. Let’s map our stream:

Now it gives us true in the beginning and false in the middle of each bar. We would use it to play audio samples:

Now let’s add melody. We will use numbers to indicate notes where 69 means middle A note. Function that translates this number to frequency can be easily found on Wikipedia. Here’s our tune:

Our component will play right frequency for each note each beat:

And inside its template we will have a real synthesizer! But first we need another pipe. It would automate volume with ADSR-envelope. That means “Attack, Decay, Sustain, Release” and here’s how it looks:

In our case we need for the sound to quickly start and then fade away. Pipe is rather simple:

Now we will use it for our synth tune:

Let’s figure out what’s going on here. We have two oscillators. First one is just a sine wave passed through ADSR pipe. Second one is same echo loop we’ve seen, except this time it passes through ConvolverNode. It creates room acoustics using impulse response. It's a big an interesting subject of its own, but it is outside this article's scope. All other tracks in our song are made similarly. Nodes are connected to each other, parameters are automated with LFOs or change smoothly via our pipes.

Conclusion

I only went over a small portion of this subject, simplifying corner cases. We’ve made a complete conversion of Web Audio API into declarative Angular open-source library @ng-web-apis/audio. It covers all the nodes and features.

If you compare Web Audio to canvas and imperative commands to draw on it, then this library is a lot like SVG.

If you want to know, what can be created with this approach, check out my little pet project — synthwave karaoke game Jamigo.app:

Jamigo.app

This library is a part of a bigger project called Web APIs for Angular — an initiative with a goal of creating lightweight, high quality wrappers of native APIs for idiomatic use with Angular. So if you want to try, say, Payment Request API or play with your MIDI keyboard in browser — you are very welcome to browse all our releases so far.

Writing Retrowave in Angular was originally published in AngularWave on Medium, where people are continuing the conversation by highlighting and responding to this story.

Previously, we spoke about declarative use of Web Audio API in Angular. Programming music is fun and all but how about actually playing it? There is a standard called MIDI. It’s a messaging protocol for electronic instruments data exchange developed back in the 80s. And Chrome supports it natively. It means if you have a synthesizer or a MIDI keyboard — you can hook it up to a computer and read what’s played in the browser. You can even control other hardware from your machine. Let’s learn how to do it the Angular way.

Web MIDI API

There’s not a lot of documentation about it other than the specs. You request access to MIDI devices from navigator and you receive all MIDI inputs and outputs in a Promise. Those inputs and outputs (also called ports) act like event targets. Communication is performed through MIDIMessageEvents which carry Uint8Array data. Each message is 3 bytes at most. The first one is called a status byte. Every number has a particular role like key press or pitch bend. Second and third integers are called data bytes. In the case of key press second byte tells us what key is pressed and the third one is the velocity (how loud note is played). Full spec is available on the official MIDI website. In Angular we handle events with Observables so first step to adopt Web MIDI API would be to convert it to RxJs.

Dependency Injection

To subscribe to events we first need to get MIDIAccess object to reach all inputs. As mentioned before, we request it from navigator and we get a Promise as a response. Thankfully, RxJs works with Promises too. We can create an Injection Token using NAVIGATOR from @ng-web-apis/common package. This way we are not using global objects directly:

Now that we have it, we can subscribe to all MIDI events. We can make Observable two ways:

1. Create a service that extends Observable like we did in Intersection Observer API
2. Create a token with a factory that would map this Promise to Observable of events

Since in this case there is not much set up required a token would suffice. With a bit of extra code to handle Promise rejection, subscribing to all events would look like this:

We can extract particular MIDI port from MIDIAccess in case we want to, say, send an outgoing message. Let's add another token and a prepared provider to do this with ease:

Did you know you don’t need to spread Provider[] when you use it in metadata? providers section of @Directive supports multidimensional array so you can use it as is!

We can add similar helpers to get outputs by name and same goes for inputs

Operators

To work with our stream we need to add some custom operators. After all, we shouldn’t always analyze raw event data to understand what we’re dealing with.

Operators can be roughly broken into two categories: monotype and mapping. With the first group, we can filter out the stream to events of interest. For example, only listen to played notes or volume sliders. Second group would alter elements for us, like dropping the rest of the event and only deliver data array.

Here’s how we can listen to messages only from a given channel (out of 16):

The status byte is organized in groups of 16: 128–143 are noteOff messages for each of the 16 channels, 144–159 are noteOn, etc. So if we divide status byte by 16 and get the reminder — we end up with that message’s channel.

If we only care about played notes, we can write the following operator:

Some MIDI controllers send explicit noteOff messages when you let go of a key. But some send noteOn with 0 velocity instead. This operator normalizes behavior to noteOn only messages. It shifts the status byte of all noteOff messages by 16 and sets the last byte to 0 effectively turning them into noteOn messages of 0 velocity.

Now we can chain such operators to get a stream we need:

Time put all this to work!

Playable synth

With a little help from our Web Audio API library discussed in my previous article, we can create a nice sounding synth with just a few directives. Then we need to feed it played notes from the stream we’ve assembled.

We will use the last code example as a starting point. To have polyphonic synthesizer we need to keep track of all played notes so we will add scan to our chain:

To alter the volume of held keys and to not end sound abruptly when we let go we will create a proper ADSR-pipe (the previous article had a simplified version):

Now when we press key volume would linearly change from 0 to the level we played it in attack time. Then it would fall to sustain level in decay time. And when we let go it would go down to 0 in release time.

With this pipe we can throw in a fine synth in the template:

We iterate over accumulated notes with built-in keyvalue pipe tracking items by played key. Then we have 2 oscillators playing those frequencies. And at the end — a reverberation effect with ConvolverNode. Pretty basic setup and not a lot of code, but it gives us a playable instrument with rich sound. You can go ahead and give it a try in our interactive demo below.

MIDI access will not be allowed in an iframe, so to play your instrument head to dedicated link: https://angular-midi.stackblitz.io/

I included mouse interaction for those who do not have a MIDI controller connected

Conclusion

In Angular, we are used to working with events using RxJs. And Web MIDI API is not much different from regular events. With some architectural decisions and tokens, we managed to use MIDI in an Angular app. The solution we created is available as @ng-web-apis/midi open-source package. It focuses mostly on receiving events. If you see something that is missing like a helper function or another operator — feel free to open an issue.

This library is a part of a bigger project called Web APIs for Angular — an initiative to create lightweight, high-quality wrappers of native APIs for idiomatic use with Angular. So if you want to try Payment Request API or need a declarative Intersection Observer — you are very welcome to browse all our releases so far.

If you want to know, what can be created with this approach, check out my little pet project — synthwave karaoke game Jamigo.app:

Jamigo.app

Jam on your MIDI keyboard in Angular was originally published in AngularWave on Medium, where people are continuing the conversation by highlighting and responding to this story.

What is a portal?

Imagine you have a select component. It has a drop-down block with suggestions. If we keep it at the same position in DOM as the hosting component, we will run into all sorts of trouble. Items pop through and containers can chop off content:

Verticality issues are often solved with z-index, effectively starting World War Z in your app. It's not uncommon to see values like 100, 10000, 10001. But even if you manage to get it right — overflow: hidden would still get you there. So what can we do? Instead of having drop-down near its host we can show it in a dedicated container on top of everything. Then your application content can live in its own isolated context eliminating z-index problems. This container is exactly what a portal is. And it is what the Taiga UI root component sets up for you, among other things. Let's look at its template:

Generic and dedicated portals

Both tui-dialog-host and tui-portal-host are portals in their nature. But they work differently. Let's explore the second one first. Taiga UI uses it mostly to display drop-downs. But it's a generic container. It is controlled by a very simple service:

And the component itself is rather straightforward. All it does is show templates and dynamic components on top of everything. No other logic is included (except a little position: fixed helper for iOS). It means that positioning, closing and the rest is handled by portal items on their own. It's a good idea to have a generic portal for special cases. Like a fixed «Scroll to top» button displayed above content or anything else you, as a library user might need.

Drop-downs

If we were to architect a drop-down — we would need to come up with a positioning solution. We have several options here:

1. Position drop-down once and prevent scrolling while it’s open. This is what material does by default.
2. Position once and close if scrolling occurred. That’s how native drop-downs behave.
3. Follow host position when it changes

We went with the third option. It’s not that trivial as it turned out. You cannot really get two positions in sync, even with requestAnimationFrame. Because once you query the host position — it triggers a layout recalculation. So by the time the next frame comes and drop-down is positioned — the host already changes location a little bit. This causes visible jumps, even on fast machines. We got around that by using absolute positioning, rather than fixed. Because the portal container wraps the entire page, position values stay the same during scroll. If the host is in a fixed container, though, it would still jump. But we can detect that when we open the drop-down and use fixed positioning for it as well.

And then there’s this:

If the host leaves the visible area — we need to close the drop-down. That’s a job for Obscured service. It detects when the host is fully obscured by anything and closes drop-down in that case.

Dialogs

For dedicated portals study we can take a look at dialogs. Toast notifications and hints are very similar but there are some interesting topics to discuss with modals.

This is how dialog host looks like:

Instead of being a generic host it has an ngFor loop over particular items. This allows us to bundle some logic in, like focus trap and page scroll blocking. There is also a clever use of dependency injection here, allowing dialogs to be design and data model agnostic. Host collects observables with dialogs through a dedicated multi token, merges these streams and shows the result. That way you can have multiple designs for dialogs in the same app. Taiga UI has two built-in designs — base and mobile. But you can easily add your own. Let's see how.

Dialog service returns Observable. When you subscribe to it, modal popup is shown, when you terminate subscription it is closed. Dialog can also send back data through that stream. First, we design our dialog component. All that's important here, really, is that you can inject POLYMORPHEUS_CONTEXT in constructor. It would contain an object with content and observer for a particular dialog instance. You can close dialog from within by calling complete on observer and you can send back data using next method. Plus all the options you will provide to the service that we will create by extending an abstract class:

In it we provide default config and a component to use and we’re all set.

Dialogs, like everything in Taiga UI use ng-polymorpheus for customizable content. You can read more about making interface free, flexible components with it in this article.

Focus trapping is handled by the tuiFocusTrap directive. Since we have drop-downs later in DOM and we can have multiple dialogs open at the same time — we don't care if focus goes farther in the DOM. If it went somewhere prior to dialog though — we return focus back with a few helpers from @taiga-ui/cdk:

Blocking page scroll is dealt with by combination of a directive and some logic inside the root component. Root just hides scrollbars when a dialog is open, while Overscroll directive takes care of touch and wheel scroll. There’s a CSS rule for overscroll behavior. However it’s not sufficient. It doesn’t help when dialog is small enough that it doesn’t have its own scroll. That’s why we have a directive with some additional logic stopping scroll if it will happen in some patent node.

Bonus: what else does tui-root do?

As far as portals go — this covers most of it. Let’s also take a quick look at what else is bundled with the root component. You saw in the template that it has tui-scroll-controls. These are custom scrollbars that control global scroll. You may have also noticed named content projections like <ng-content select="tuiOverDialogs"></ng-content>. With those you can slide some content in-between layers of Taiga UI if you need. For example, if you run another library for toasts or dialogs and want them properly placed vertically.

It also registers several event manager plugins in the DI. You can read about them in a dedicated article. It is important that TuiRootModule goes after BrowserModule so they are registered at the right order. But don't worry — if you get it wrong you will see an assertion message in the console.

That wraps it up for portals and the root component. Taiga UI is open-source and you can check it out on GitHub and npm. You can also browse the demo portal with documentation and play with it using this StackBlitz starter. Stay tuned for more articles on interesting features we have!

Demystifying Taiga UI root component: portals pattern in Angular was originally published in AngularWave on Medium, where people are continuing the conversation by highlighting and responding to this story.

In JavaScript we often use entities, such as window, navigator, requestAnimationFrame or location. Some of these objects have been there forever, some are parts of the ever-growing Web APIs feature set. You might have seen Location class or DOCUMENT token used in Angular. Let's discuss why they exist and what we can learn from them to make our apps cleaner and more flexible.

DOCUMENT

DOCUMENT is a built-in Angular token. Here's how you can use it. Instead of this:

You can write this:

In the first code snippet we accessed global variable directly. In the second example we injected it as a dependency to constructor. I’m not going to throw fancy acronyms at you or say that the first approach breaks some programming principles or patterns. To be honest, I’m not that fluent in those. Instead, I will show you exactly why token approach is better. And we will start by taking a look at where this token comes from. There’s nothing special about its declaration in the @angular/common package:

Inside @angular/platform-browser, however, we see it getting actual value (code snippet simplified):

When you add BrowserModule to your app.browser.module.ts you register a bunch of different implementations for built-in tokens, such as RendererFactory2, Sanitizer, EventManager and our DOCUMENT. Why is it like that? Because Angular is multiplatform framework. Or rather platform agnostic. It works with abstractions and utilizes dependency injection mechanism heavily to be able to work in browser, on server or mobile platforms. To figure it out, let's take a sneak peak at ServerModule — another bundled platform (code snippet simplified):

We see that it uses domino to create an imitation of a document, based on some config it once again got from the DI. This is what you get when you, for example, use Angular Universal for server side rendering. We already see the first and most important benefit. Using DOCUMENT token would work in SSR environment whereas accessing global document will not.

Other global entities

So Angular team took care of document for us which is nice. But what if we want to check our browser with userAgent string? To do so we would typically access navigator.userAgent. What this actually means is that we first reach for global object, window in browser environment, and then get its navigator property. So let's start by implementing WINDOW token. It is pretty easy to do with a factory that you can add to token declaration:

This is enough to start using WINDOW token similar to DOCUMENT. Now we can use similar approach to create NAVIGATOR:

We will take it one step further and create a token for USER_AGENT the same way. Why? We'll see later!

Sometimes making a simple token is not enough. Angular’s Location class is basically a wrapper over native location that improves our dev experience. Since we are used to RxJS streams let's replace requestAnimationFrame with an Observable implementation:

We skipped PERFORMANCE token creation because it follows the same pattern. Now we have a single shared requestAnimationFrame based stream of timestamps which we can use across our app. After we replaced everything with tokens our components no longer rely on magically available items and get everything they depend on from dependency injection, which is neat.

Server Side Rendering

Now say in our app we want to do window.matchMedia('(prefers-color-scheme: dark)'). While there is certainly something in our WINDOW token on the server side, it definitely does not provide full API that Window object has. If we try the above method in SSR we would probably get undefined is not a function error. One thing we can do is wrap such cases with isPlatformBrowser checks but that's boring. Advantage of DI is we can override stuff. So instead of handling these situation as special cases we can provide WINDOW in our app.server.module.ts with a type-safe mock object that will protect us from non-existent properties.

This showcases another important advantage this approach has: token values can be replaced. This makes it very easy to test components that rely on browser API, especially if you test in Jest where native API is not available otherwise. But mocks are dull. Sometimes we can actually provide something meaningful. In SSR environment we have request object which contains user agent data. That’s why we separated it into its own token — because we can actually obtain it separately sometimes. Here’s how we can turn request into provider:

And use it in our server.ts when we are setting up Angular Universal:

Node.js also has its own implementation of Performance which we can use on the server side:

In case of requestAnimationFrame we will not need Performance though. We probably do not want our Observable chain to run on the server so we can provide EMPTY:

We can follow this pattern to «tokenize» all global objects that we use across our app and provide replacements for various platforms we might run it on.

Wrapping up

With this approach your code becomes well abstracted. Even if you do not run it on the server now, you might want to do it later and you will be ready. Besides, it is much easier to test code when things it relies upon can be substituted. We have created a tiny library of common tokens that we use:

ng-web-apis/common

If you need something that is currently missing, feel free to create an issue! There is also a sidekick package with SSR versions of those tokens:

ng-web-apis/universal

You can explore this Rick and Morty themed project by Igor Katsuba using SSR to see all this in action. If you are interested in Angular Universal in particular, read his article about issues he faced and how to overcome them.

Thanks to this pattern our Angular components library Taiga UI was able to run on both Angular Universal and Ionic setups with no extra fuss. I hope it will be beneficial to you as well.

Global objects in Angular was originally published in AngularWave on Medium, where people are continuing the conversation by highlighting and responding to this story.