Accessibility in Angular link

The web is used by a wide variety of people, including those who have visual or motor impairments. A variety of assistive technologies are available that make it much easier for these groups to interact with web-based software applications. Also, designing an application to be more accessible generally improves the user experience for all users.

For an in-depth introduction to issues and techniques for designing accessible applications, see the Accessibility section of the Google's Web Fundamentals.

This page discusses best practices for designing Angular applications that work well for all users, including those who rely on assistive technologies.

Accessibility attributes link

Building accessible web experience often involves setting Accessible Rich Internet Applications (ARIA) attributes to provide semantic meaning where it might otherwise be missing. Use attribute binding template syntax to control the values of accessibility-related attributes.

When binding to ARIA attributes in Angular, you must use the attr. prefix. The ARIA specification depends specifically on HTML attributes rather than properties of DOM elements.

      
        content_copy
      
      <!-- Use attr. when binding to an ARIA attribute -->
<button [attr.aria-label]="myActionLabel">…</button>
    

      
        content_copy
      
      <!-- Static ARIA attributes require no extra syntax -->
<button aria-label="Save document">…</button>
    

Angular UI components link

The Angular Material library, which is maintained by the Angular team, is a suite of reusable UI components that aims to be fully accessible. The Component Development Kit (CDK) includes the a11y package that provides tools to support various areas of accessibility. For example:

• LiveAnnouncer is used to announce messages for screen-reader users using an aria-live region. See the W3C documentation for more information on aria-live regions.

• The cdkTrapFocus directive traps Tab-key focus within an element. Use it to create accessible experience for components such as modal dialogs, where focus must be constrained.

For full details of these and other tools, see the Angular CDK accessibility overview.

Augmenting native elements link

Native HTML elements capture several standard interaction patterns that are important to accessibility. When authoring Angular components, you should re-use these native elements directly when possible, rather than re-implementing well-supported behaviors.

For example, instead of creating a custom element for a new variety of button, create a component that uses an attribute selector with a native <button> element. This most commonly applies to <button> and <a> , but can be used with many other types of element.

You can see examples of this pattern in Angular Material: MatButton , MatTabNav , and MatTable .

Using containers for native elements link

Sometimes using the appropriate native element requires a container element. For example, the native <input> element cannot have children, so any custom text entry components need to wrap an <input> with extra elements. By just including <input> in your custom component's template, it's impossible for your component's users to set arbitrary properties and attributes to the <input> element. Instead, create a container component that uses content projection to include the native control in the component's API.

You can see MatFormField as an example of this pattern.

Case study: Building a custom progress bar link

The following example shows how to make a progress bar accessible by using host binding to control accessibility-related attributes.

• The component defines an accessibility-enabled element with both the standard HTML attribute role , and ARIA attributes. The ARIA attribute aria-valuenow is bound to the user's input.

  src/app/progress-bar.component.ts

        
          content_copy
        
        import { Component, Input } from '@angular/core';
  
  /**
   * Example progressbar component.
   */
  @Component({
    selector: 'app-example-progressbar',
    template: '<div class="bar" [style.width.%]="value"></div>',
    styleUrls: ['./progress-bar.component.css'],
    host: {
      // Sets the role for this component to "progressbar"
      role: 'progressbar',
  
      // Sets the minimum and maximum values for the progressbar role.
      'aria-valuemin': '0',
      'aria-valuemax': '100',
  
      // Binding that updates the current value of the progressbar.
      '[attr.aria-valuenow]': 'value',
    }
  })
  export class ExampleProgressbarComponent  {
    /** Current value of the progressbar. */
    @Input() value = 0;
  }
      

• In the template, the aria-label attribute ensures that the control is accessible to screen readers.

  src/app/app.component.html

        
          content_copy
        
        <label>
    Enter an example progress value
    <input type="number" min="0" max="100"
        [value]="progress" (input)="setProgress($event)">
  </label>
  
  <!-- The user of the progressbar sets an aria-label to communicate what the progress means. -->
  <app-example-progressbar [value]="progress" aria-label="Example of a progress bar">
  </app-example-progressbar>
      

Routing link

Focus management after navigation link

Tracking and controlling focus in a UI is an important consideration in designing for accessibility. When using Angular routing, you should decide where page focus goes upon navigation.

To avoid relying solely on visual cues, you need to make sure your routing code updates focus after page navigation. Use the NavigationEnd event from the Router service to know when to update focus.

The following example shows how to find and focus the main content header in the DOM after navigation.

      
        content_copy
      
      router.events.pipe(filter(e => e instanceof NavigationEnd)).subscribe(() => {
  const mainHeader = document.querySelector('#main-content-header')
  if (mainHeader) {
    mainHeader.focus();
  }
});
    

In a real application, the element that receives focus depends on your specific application structure and layout. The focused element should put users in a position to immediately move into the main content that has just been routed into view. You should avoid situations where focus returns to the body element after a route change.

Active links identification link

CSS classes applied to active RouterLink elements, such as RouterLinkActive , provide a visual cue to identify the active link. Unfortunately, a visual cue doesn't help blind or visually impaired users. Applying the aria-current attribute to the element can help identify the active link. For more information, see Mozilla Developer Network (MDN) aria-current).

The RouterLinkActive directive provides the ariaCurrentWhenActive input which sets the aria-current to a specified value when the link becomes active.

The following example shows how to apply the active-page class to active links as well as setting their aria-current attribute to "page" when they are active:

      
        content_copy
      
      <nav>
  <a routerLink="home"
     routerLinkActive="active-page"
     ariaCurrentWhenActive="page">
    Home
  </a>
  <a routerLink="about"
     routerLinkActive="active-page"
     ariaCurrentWhenActive="page">
    About
  </a>
  <a routerLink="shop"
     routerLinkActive="active-page"
     ariaCurrentWhenActive="page">
    Shop
  </a>
</nav>
    

More information link

• Accessibility - Google Web Fundamentals
• ARIA specification and authoring practices
• Material Design - Accessibility
• Smashing Magazine
• Inclusive Components
• Accessibility Resources and Code Examples
• W3C - Web Accessibility Initiative
• Rob Dodson A11ycasts
• Angular ESLint provides linting rules that can help you make sure your code meets accessibility standards.

Books

• "A Web for Everyone: Designing Accessible User Experiences," Sarah Horton and Whitney Quesenbery
• "Inclusive Design Patterns," Heydon Pickering

AngularJS to Angular concepts: Quick reference link

Angular is the name for the Angular of today and tomorrow.

AngularJS is the name for all v1.x versions of Angular.

This guide helps you transition from AngularJS to Angular by mapping AngularJS syntax to the corresponding Angular syntax.

See the Angular syntax in this live example / download example .

Template basics link

Templates are the user-facing part of an Angular application and are written in HTML. The following table lists some of the key AngularJS template features with their corresponding Angular template syntax.

Bindings / interpolation → bindings / interpolation link

      
      Your favorite hero is: {{vm.favoriteHero}}
    

      
      Your favorite hero is: {{favoriteHero}}
    

Filters → pipes link

      
      <td> 
  {{movie.title | uppercase}} 
</td>
    

      
      <td>{{movie.title | uppercase}}</td>
    

Local variables → input variables link

      
      <tr ng-repeat="movie in vm.movies"> 
  <td> 
    {{movie.title}} 
  </td> 
</tr>
    

      
      <tr *ngFor="let movie of movies">
  <td>{{movie.title}}</td>
</tr>
    

Template directives link

AngularJS provides more than seventy built-in directives for templates. Many of them are not needed in Angular because of its more capable and expressive binding system. The following are some of the key AngularJS built-in directives and their equivalents in Angular.

ng-app → bootstrapping link

      
      <body ng-app="movieHunter">
    

      
      import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';

import { AppModule } from './app/app.module';

platformBrowserDynamic().bootstrapModule(AppModule)
  .catch(err => console.error(err));
    

      
      import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';

import { AppComponent } from './app.component';

@NgModule({
  imports: [ BrowserModule ],
  declarations: [ AppComponent ],
  bootstrap: [ AppComponent ]
})
export class AppModule { }
    

ng-class → ngClass link

      
      <div ng-class="{active: isActive}"> 
<div ng-class="{active: isActive, shazam: isImportant}">
    

      
      <div [ngClass]="{'active': isActive}">
<div [ngClass]="{'active': isActive,
                 'shazam': isImportant}">
<div [class.active]="isActive">
    

ng-click → Bind to the click event link

      
      <button ng-click="vm.toggleImage()"> 
<button ng-click="vm.toggleImage($event)">
    

      
      <button type="button" (click)="toggleImage()">
<button type="button" (click)="toggleImage($event)">
    

ng-controller → component decorator link

      
      <div ng-controller="MovieListCtrl as vm">
    

      
      @Component({
  selector: 'app-movie-list',
  templateUrl: './movie-list.component.html',
  styleUrls: [ './movie-list.component.css' ],
})
    

ng-hide → Bind to the hidden property link

ng-href → Bind to the href property link

      
      <a ng-href="{{ angularDocsUrl }}"> 
  Angular Docs 
</a>
    

      
      <a ng-href="#{{ moviesHash }}"> 
  Movies 
</a>
    

      
      <a [href]="angularDocsUrl">Angular Docs</a>
    

      
      <a [routerLink]="['/movies']">Movies</a>
    

ng-if → *ngIf link

      
      <table ng-if="movies.length">
    

      
      <table *ngIf="movies.length">
    

ng-model → ngModel link

      
      <input ng-model="vm.favoriteHero" />
    

      
      <input [(ngModel)]="favoriteHero" />
    

ng-repeat → *ngFor link

      
      <tr ng-repeat="movie in vm.movies">
    

      
      <tr *ngFor="let movie of movies">
    

ng-show → Bind to the hidden property link

      
      <h3 ng-show="vm.favoriteHero"> 
  Your favorite hero is: {{vm.favoriteHero}} 
</h3>
    

      
      <h3 [hidden]="!favoriteHero">
  Your favorite hero is: {{favoriteHero}}
</h3>
    

ng-src → Bind to the src property link

      
      <img ng-src="{{movie.imageurl}}">
    

      
      <img [src]="movie.imageurl" [alt]="movie.title">
    

ng-style → ngStyle link

      
      <div ng-style="{color: colorPreference}">
    

      
      <div [ngStyle]="{'color': colorPreference}">
<div [style.color]="colorPreference">
    

ng-switch → ngSwitch link

      
      <div ng-switch="vm.favoriteHero && vm.checkMovieHero(vm.favoriteHero)"> 
  <div ng-switch-when="true"> 
    Excellent choice. 
  </div> 
  <div ng-switch-when="false"> 
    No movie, sorry. 
  </div> 
  <div ng-switch-default> 
    Please enter your favorite hero. 
  </div> 
</div>
    

      
      <span [ngSwitch]="favoriteHero &&
               checkMovieHero(favoriteHero)">
  <p *ngSwitchCase="true">
    Excellent choice!
  </p>
  <p *ngSwitchCase="false">
    No movie, sorry!
  </p>
  <p *ngSwitchDefault>
    Please enter your favorite hero.
  </p>
</span>
    

Filters / pipes link

Angular pipes provide formatting and transformation for data in the template, like AngularJS filters . Many of the built-in filters in AngularJS have corresponding pipes in Angular. For more information on pipes, see Pipes.

currency → currency link

      
      <td> 
  {{movie.price | currency}} 
</td>
    

      
      <td>{{movie.price | currency:'USD':true}}</td>
    

date → date link

      
      <td> 
  {{movie.releaseDate | date}} 
</td>
    

      
      <td>{{movie.releaseDate | date}}</td>
    

filter → none link

      
      <tr ng-repeat="movie in movieList | filter: {title:listFilter}">
    

json → json link

      
      <pre> 
  {{movie | json}} 
</pre>
    

      
      <pre>{{movie | json}}</pre>
    

limitTo → slice link

      
      <tr ng-repeat="movie in movieList | limitTo:2:0">
    

      
      <tr *ngFor="let movie of movies | slice:0:2">
    

lowercase → lowercase link

      
      <td> 
  {{movie.title | lowercase}} 
</td>
    

      
      <td>{{movie.title | lowercase}}</td>
    

number → number link

      
      <td> 
  {{movie.starRating | number}} 
</td>
    

      
      <td>{{movie.starRating | number}}</td>
<td>{{movie.starRating | number:'1.1-2'}}</td>
<td>{{movie.approvalRating | percent: '1.0-2'}}</td>
    

orderBy → none link

      
      <tr ng-repeat="movie in movieList | orderBy : 'title'">
    

Modules / controllers / components link

In both AngularJS and Angular, modules help you organize your application into cohesive blocks of features.

In AngularJS, you write the code that provides the model and the methods for the view in a controller . In Angular, you build a component .

Because much AngularJS code is in JavaScript, JavaScript code is shown in the AngularJS column. The Angular code is shown using TypeScript.

Immediately invoked function expression (IIFE) → none link

      
      ( 
  function () { 
    … 
  }() 
);
    

Angular modules → NgModules link

      
      angular .module( 
  "movieHunter", 
  [ 
    "ngRoute" 
  ] 
);
    

      
      import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';

import { AppComponent } from './app.component';

@NgModule({
  imports: [ BrowserModule ],
  declarations: [ AppComponent ],
  bootstrap: [ AppComponent ]
})
export class AppModule { }
    

Controller registration → component decorator link

      
      angular .module( 
  "movieHunter" 
) .controller( 
  "MovieListCtrl", 
  [ 
    "movieService", 
    MovieListCtrl 
  ] 
);
    

      
      @Component({
  selector: 'app-movie-list',
  templateUrl: './movie-list.component.html',
  styleUrls: [ './movie-list.component.css' ],
})
    

Controller function → component class link

      
      function MovieListCtrl(movieService) { 
}
    

      
      export class MovieListComponent {
}
    

Dependency injection → dependency injection link

      
      MovieListCtrl.$inject = [ 
  'MovieService' 
]; 
function MovieListCtrl(movieService) { 
}
    

      
      constructor(movieService: MovieService) {
}
    

Style sheets link

Style sheets give your application a nice look. In AngularJS, you specify the style sheets for your entire application. As the application grows over time, the styles for the many parts of the application merge, which can cause unexpected results. In Angular, you can still define style sheets for your entire application. Now you can also encapsulate a style sheet within a specific component.

Link tag → styles configuration or styleUrls link

      
      <link href="styles.css" 
      rel="stylesheet" />
    

      
      "styles": [
  "styles.css"
],
    

      
      styleUrls: [ './movie-list.component.css' ],
    

Angular compiler options link

When you use ahead-of-time compilation (AOT), you can control how your application is compiled by specifying template compiler options in the TypeScript configuration file.

The template options object, angularCompilerOptions , is a sibling to the compilerOptions object that supplies standard options to the TypeScript compiler.

      
        content_copy
      
      {
  "compileOnSave": false,
  "compilerOptions": {
    "baseUrl": "./",
    // ...
  },
  "angularCompilerOptions": {
    "enableI18nLegacyMessageIdFormat": false,
    "strictInjectionParameters": true,
    // ...
  }
}
    

Configuration inheritance with extends link

Like the TypeScript compiler, the Angular AOT compiler also supports extends in the angularCompilerOptions section of the TypeScript configuration file. The extends property is at the top level, parallel to compilerOptions and angularCompilerOptions .

A TypeScript configuration can inherit settings from another file using the extends property. The configuration options from the base file are loaded first, then overridden by those in the inheriting configuration file.

For example:

      
        content_copy
      
      {
    "extends": "./tsconfig.json",
    "compilerOptions": {
      "outDir": "./out-tsc/app",
    // ...
    "angularCompilerOptions": {
      "strictTemplates": true,
      "preserveWhitespaces": true,
      // ...
    }
  }
    

For more information, see the TypeScript Handbook.

Template options link

The following options are available for configuring the AOT template compiler.

allowEmptyCodegenFiles link

When true , create all possible files even if they are empty. Default is false . Used by the Bazel build rules to simplify how Bazel rules track file dependencies. Do not use this option outside of the Bazel rules.

annotationsAs link

Modifies how Angular-specific annotations are emitted to improve tree-shaking. Non-Angular annotations are not affected. One of static fields or decorators . The default value is static fields .

• By default, the compiler replaces decorators with a static field in the class, which allows advanced tree-shakers like Closure compiler to remove unused classes

• The decorators value leaves the decorators in place, which makes compilation faster. TypeScript emits calls to the __decorate helper. Use --emitDecoratorMetadata for runtime reflection.

  NOTE :
  That the resulting code cannot tree-shake properly.

annotateForClosureCompiler link

When true , use Tsickle to annotate the emitted JavaScript with JSDoc comments needed by the Closure Compiler. Default is false .

compilationMode link

Specifies the compilation mode to use. The following modes are available:

The default value is 'full' .

disableExpressionLowering link

When true , the default, transforms code that is or could be used in an annotation, to allow it to be imported from template factory modules. See metadata rewriting for more information.

When false , disables this rewriting, requiring the rewriting to be done manually.

disableTypeScriptVersionCheck link

When true , the compiler does not look at the TypeScript version and does not report an error when an unsupported version of TypeScript is used. Not recommended, as unsupported versions of TypeScript might have undefined behavior. Default is false .

enableI18nLegacyMessageIdFormat link

Instructs the Angular template compiler to create legacy ids for messages that are tagged in templates by the i18n attribute. See Mark text for translations for more information about marking messages for localization.

Set this option to false unless your project relies upon translations that were created earlier using legacy IDs. Default is true .

The pre-Ivy message extraction tooling created a variety of legacy formats for extracted message IDs. These message formats have some issues, such as whitespace handling and reliance upon information inside the original HTML of a template.

The new message format is more resilient to whitespace changes, is the same across all translation file formats, and can be created directly from calls to $localize . This allows $localize messages in application code to use the same ID as identical i18n messages in component templates.

enableResourceInlining link

When true , replaces the templateUrl and styleUrls properties in all @Component decorators with inline content in the template and styles properties.

When enabled, the .js output of ngc does not include any lazy-loaded template or style URLs.

For library projects created with the Angular CLI, the development configuration default is true .

enableLegacyTemplate link

When true , enables the deprecated <template> element in place of <ng-template> . Default is false . Might be required by some third-party Angular libraries.

flatModuleId link

The module ID to use for importing a flat module (when flatModuleOutFile is true ). References created by the template compiler use this module name when importing symbols from the flat module. Ignored if flatModuleOutFile is false .

flatModuleOutFile link

When true , generates a flat module index of the given filename and the corresponding flat module metadata. Use to create flat modules that are packaged similarly to @angular/core and @angular/common . When this option is used, the package.json for the library should refer to the created flat module index instead of the library index file.

Produces only one .metadata.json file, which contains all the metadata necessary for symbols exported from the library index. In the created .ngfactory.js files, the flat module index is used to import symbols. Symbols that include both the public API from the library index as well as shrouded internal symbols.

By default the .ts file supplied in the files field is assumed to be the library index. If more than one .ts file is specified, libraryIndex is used to select the file to use. If more than one .ts file is supplied without a libraryIndex , an error is produced.

A flat module index .d.ts and .js is created with the given flatModuleOutFile name in the same location as the library index .d.ts file.

For example, if a library uses the public_api.ts file as the library index of the module, the tsconfig.json files field would be ["public_api.ts"] . The flatModuleOutFile option could then be set, for example, to "index.js" , which produces index.d.ts and index.metadata.json files. The module field of the library's package.json would be "index.js" and the typings field would be "index.d.ts" .

fullTemplateTypeCheck link

When true , the recommended value, enables the binding expression validation phase of the template compiler. This phase uses TypeScript to verify binding expressions. For more information, see Template type checking.

Default is false , but when you use the Angular CLI command ng new --strict , it is set to true in the new project's configuration.

generateCodeForLibraries link

When true , creates factory files ( .ngfactory.js and .ngstyle.js ) for .d.ts files with a corresponding .metadata.json file. The default value is true .

When false , factory files are created only for .ts files. Do this when using factory summaries.

preserveWhitespaces link

When false , the default, removes blank text nodes from compiled templates, which results in smaller emitted template factory modules. Set to true to preserve blank text nodes.

skipMetadataEmit link

When true , does not produce .metadata.json files. Default is false .

The .metadata.json files contain information needed by the template compiler from a .ts file that is not included in the .d.ts file produced by the TypeScript compiler. This information includes, for example, the content of annotations, such as a component's template, which TypeScript emits to the .js file but not to the .d.ts file.

You can set to true when using factory summaries, because the factory summaries include a copy of the information that is in the .metadata.json file.

Set to true if you are using TypeScript's --outFile option, because the metadata files are not valid for this style of TypeScript output. The Angular community does not recommend using --outFile with Angular. Use a bundler, such as webpack, instead.

skipTemplateCodegen link

When true , does not emit .ngfactory.js and .ngstyle.js files. This turns off most of the template compiler and disables the reporting of template diagnostics.

Can be used to instruct the template compiler to produce .metadata.json files for distribution with an npm package. This avoids the production of .ngfactory.js and .ngstyle.js files that cannot be distributed to npm .

For library projects created with the Angular CLI, the development configuration default is true .

strictMetadataEmit link

When true , reports an error to the .metadata.json file if "skipMetadataEmit" is false . Default is false . Use only when "skipMetadataEmit" is false and "skipTemplateCodegen" is true .

This option is intended to verify the .metadata.json files emitted for bundling with an npm package. The validation is strict and can emit errors for metadata that would never produce an error when used by the template compiler. You can choose to suppress the error emitted by this option for an exported symbol by including @dynamic in the comment documenting the symbol.

It is valid for .metadata.json files to contain errors. The template compiler reports these errors if the metadata is used to determine the contents of an annotation. The metadata collector cannot predict the symbols that are designed for use in an annotation. It preemptively includes error nodes in the metadata for the exported symbols. The template compiler can then use the error nodes to report an error if these symbols are used.

If the client of a library intends to use a symbol in an annotation, the template compiler does not normally report this. It gets reported after the client actually uses the symbol. This option allows detection of these errors during the build phase of the library and is used, for example, in producing Angular libraries themselves.

For library projects created with the Angular CLI, the development configuration default is true .

strictInjectionParameters link

When true , reports an error for a supplied parameter whose injection type cannot be determined. When false , constructor parameters of classes marked with @Injectable whose type cannot be resolved produce a warning. The recommended value is true , but the default value is false .

When you use the Angular CLI command ng new --strict , it is set to true in the created project's configuration.

strictTemplates link

When true , enables strict template type checking.

The strictness flags that this open enables allow you to turn on and off specific types of strict template type checking. See troubleshooting template errors.

When you use the Angular CLI command ng new --strict , it is set to true in the new project's configuration.

trace link

When true , prints extra information while compiling templates. Default is false .

Command line options link

Most of the time you interact with the Angular Compiler indirectly using Angular CLI. When debugging certain issues, you might find it useful to invoke the Angular Compiler directly. You can use the ngc command provided by the @angular/compiler-cli npm package to call the compiler from the command line.

The ngc command is just a wrapper around TypeScript's tsc compiler command and is primarily configured via the tsconfig.json configuration options documented in the previous sections.

Besides the configuration file, you can also use tsc command line options to configure ngc .

Angular package format link

This document describes the Angular Package Format (APF). APF is an Angular specific specification for the structure and format of npm packages that is used by all first-party Angular packages ( @angular/core , @angular/material , etc.) and most third-party Angular libraries.

APF enables a package to work seamlessly under most common scenarios that use Angular. Packages that use APF are compatible with the tooling offered by the Angular team as well as wider JavaScript ecosystem. It is recommended that third-party library developers follow the same npm package format.

Why specify a package format? link

In today's JavaScript landscape, developers consume packages in many different ways, using many different toolchains (Webpack, rollup, esbuild, etc.). These tools may understand and require different inputs - some tools may be able to process the latest ES language version, while others may benefit from directly consuming an older ES version.

The Angular distribution format supports all of the commonly used development tools and workflows, and adds emphasis on optimizations that result either in smaller application payload size or faster development iteration cycle (build time).

Developers can rely on Angular CLI and ng-packagr (a build tool Angular CLI uses) to produce packages in the Angular package format. See the Creating Libraries guide for more details.

File layout link

The following example shows a simplified version of the @angular/core package's file layout, with an explanation for each file in the package.

This table describes the file layout under node_modules/@angular/core annotated to describe the purpose of files and directories:

package.json link

The primary package.json contains important package metadata, including the following:

• It declares the package to be in EcmaScript Module (ESM) format

• It contains an "exports" field which defines the available source code formats of all entrypoints

• It contains keys which define the available source code formats of the primary @angular/core entrypoint, for tools which do not understand "exports" . These keys are considered deprecated, and could be removed as the support for "exports" rolls out across the ecosystem.

• It declares whether the package contains side effects

ESM declaration link

The top-level package.json contains the key:

      
        content_copy
      
      {
  "type": "module"
}
    

This informs resolvers that code within the package is using EcmaScript Modules as opposed to CommonJS modules.

"exports" link

The "exports" field has the following structure:

      
        content_copy
      
      "exports": {
  "./schematics/*": {
    "default": "./schematics/*.js"
  },
  "./package.json": {
    "default": "./package.json"
  },
  ".": {
    "types": "./core.d.ts",
    "esm2020": "./esm2020/core.mjs",
    "es2020": "./fesm2020/core.mjs",
    "es2015": "./fesm2015/core.mjs",
    "node": "./fesm2015/core.mjs",
    "default": "./fesm2020/core.mjs"
  },
  "./testing": {
    "types": "./testing/testing.d.ts",
    "esm2020": "./esm2020/testing/testing.mjs",
    "es2020": "./fesm2020/testing.mjs",
    "es2015": "./fesm2015/testing.mjs",
    "node": "./fesm2015/testing.mjs",
    "default": "./fesm2020/testing.mjs"
  }
}
    

Of primary interest are the "." and the "./testing" keys, which define the available code formats for the @angular/core primary entrypoint and the @angular/core/testing secondary entrypoint, respectively. For each entrypoint, the available formats are:

Tooling that is aware of these keys may preferentially select a desirable code format from "exports" . The remaining 2 keys control the default behavior of tooling:

• "node" selects flattened ES2015 code when the package is loaded in Node.

  This format is used due to the requirements of zone.js , which does not support native async / await ES2017 syntax. Therefore, Node is instructed to use ES2015 code, where async / await structures have been downleveled into Promises.

• "default" selects flattened ES2020 code for all other consumers.

Libraries may want to expose additional static files which are not captured by the exports of the JavaScript-based entry-points such as Sass mixins or pre-compiled CSS.

For more information, see Managing assets in a library.

Legacy resolution keys link

In addition to "exports" , the top-level package.json also defines legacy module resolution keys for resolvers that don't support "exports" . For @angular/core these are:

      
        content_copy
      
      {
  "fesm2020": "./fesm2020/core.mjs",
  "fesm2015": "./fesm2015/core.mjs",
  "esm2020": "./esm2020/core.mjs",
  "typings": "./core.d.ts",
  "module": "./fesm2015/core.mjs",
  "es2020": "./fesm2020/core.mjs",
}
    

As shown in the preceding code snippet, a module resolver can use these keys to load a specific code format.

Side effects link

The last function of package.json is to declare whether the package has side effects.

      
        content_copy
      
      {
  "sideEffects": false
}
    

Most Angular packages should not depend on top-level side effects, and thus should include this declaration.

Entrypoints and code splitting link

Packages in the Angular Package Format contain one primary entrypoint and zero or more secondary entrypoints (for example, @angular/common/http ). Entrypoints serve several functions.

1. They define the module specifiers from which users import code (for example, @angular/core and @angular/core/testing ).

   Users typically perceive these entrypoints as distinct groups of symbols, with different purposes or capability.

   Specific entrypoints might only be used for special purposes, such as testing. Such APIs can be separated out from the primary entrypoint to reduce the chance of them being used accidentally or incorrectly.

2. They define the granularity at which code can be lazily loaded.

   Many modern build tools are only capable of "code splitting" (aka lazy loading) at the ES Module level. The Angular Package Format uses primarily a single "flat" ES Module per entry point. This means that most build tooling is not able to split code with a single entry point into multiple output chunks.

The general rule for APF packages is to use entrypoints for the smallest sets of logically connected code possible. For example, the Angular Material package publishes each logical component or set of components as a separate entrypoint - one for Button, one for Tabs, etc. This allows each Material component to be lazily loaded separately, if desired.

Not all libraries require such granularity. Most libraries with a single logical purpose should be published as a single entrypoint. @angular/core for example uses a single entrypoint for the runtime, because the Angular runtime is generally used as a single entity.

Resolution of secondary entry points link

Secondary entrypoints can be resolved via the "exports" field of the package.json for the package.

README.md link

The README file in the Markdown format that is used to display description of a package on npm and GitHub.

Example README content of @angular/core package:

      
        content_copy
      
      Angular
=======

The sources for this package are in the main [Angular](https://github.com/angular/angular) repo.Please file issues and pull requests against that repo.

License: MIT
    

Partial compilation link

Libraries in the Angular Package Format must be published in "partial compilation" mode. This is a compilation mode for ngc which produces compiled Angular code that is not tied to a specific Angular runtime version, in contrast to the full compilation used for applications, where the Angular compiler and runtime versions must match exactly.

To partially compile Angular code, use the compilationMode flag in the angularCompilerOptions property of your tsconfig.json :

      
        content_copy
      
      {
  …
  "angularCompilerOptions": {
    "compilationMode": "partial",
  }
}
    

Partially compiled library code is then converted to fully compiled code during the application build process by the Angular CLI.

If your build pipeline does not use the Angular CLI then refer to the Consuming partial ivy code outside the Angular CLI guide.

Optimizations link

Flattening of ES modules link

The Angular Package Format specifies that code be published in "flattened" ES module format. This significantly reduces the build time of Angular applications as well as download and parse time of the final application bundle. Please check out the excellent post "The cost of small modules" by Nolan Lawson.

The Angular compiler can generate index ES module files. Tools like Rollup can use these files to generate flattened modules in a Flattened ES Module (FESM) file format.

FESM is a file format created by flattening all ES Modules accessible from an entrypoint into a single ES Module. It's formed by following all imports from a package and copying that code into a single file while preserving all public ES exports and removing all private imports.

The abbreviated name, FESM, pronounced phe-som , can be followed by a number such as FESM5 or FESM2015. The number refers to the language level of the JavaScript inside the module. Accordingly a FESM5 file would be ESM+ES5 and include import/export statements and ES5 source code.

To generate a flattened ES Module index file, use the following configuration options in your tsconfig.json file:

      
        content_copy
      
      {
  "compilerOptions": {
    …
    "module": "esnext",
    "target": "es2020",
    …
  },
  "angularCompilerOptions": {
    …
    "flatModuleOutFile": "my-ui-lib.js",
    "flatModuleId": "my-ui-lib"
  }
}
    

Once the index file (for example, my-ui-lib.js ) is generated by ngc, bundlers and optimizers like Rollup can be used to produce the flattened ESM file.

Note about the defaults in package.json link

As of webpack v4, the flattening of ES modules optimization should not be necessary for webpack users. It should be possible to get better code-splitting without flattening of modules in webpack. In practice, size regressions can still be seen when using unflattened modules as input for webpack v4. This is why module and es2020 package.json entries still point to FESM files. This issue is being investigated. It is expected to switch the module and es2020 package.json entry points to unflattened files after the size regression issue is resolved. The APF currently includes unflattened ESM2020 code for the purpose of validating such a future change.

"sideEffects" flag link

By default, EcmaScript Modules are side-effectful: importing from a module ensures that any code at the top level of that module should run. This is often undesirable, as most side-effectful code in typical modules is not truly side-effectful, but instead only affects specific symbols. If those symbols are not imported and used, it's often desirable to remove them in an optimization process known as tree-shaking, and the side-effectful code can prevent this.

Build tools such as Webpack support a flag which allows packages to declare that they do not depend on side-effectful code at the top level of their modules, giving the tools more freedom to tree-shake code from the package. The end result of these optimizations should be smaller bundle size and better code distribution in bundle chunks after code-splitting. This optimization can break your code if it contains non-local side-effects - this is however not common in Angular applications and it's usually a sign of bad design. The recommendation is for all packages to claim the side-effect free status by setting the sideEffects property to false , and that developers follow the Angular Style Guide which naturally results in code without non-local side-effects.

More info: webpack docs on side effects

ES2020 language level link

ES2020 Language level is now the default language level that is consumed by Angular CLI and other tooling. The Angular CLI down-levels the bundle to a language level that is supported by all targeted browsers at application build time.

d.ts bundling / type definition flattening link

As of APF v8 it is now preferred to run API Extractor, to bundle TypeScript definitions so that the entire API appears in a single file.

In prior APF versions each entry point would have a src directory next to the .d.ts entry point and this directory contained individual d.ts files matching the structure of the original source code. While this distribution format is still allowed and supported, it is highly discouraged because it confuses tools like IDEs that then offer incorrect autocompletion, and allows users to depend on deep-import paths which are typically not considered to be public API of a library or a package.

Tslib link

As of APF v10, it is recommended to add tslib as a direct dependency of your primary entry-point. This is because the tslib version is tied to the TypeScript version used to compile your library.

Examples link

• @angular/core package
• @angular/material package

Definition of terms link

The following terms are used throughout this document intentionally. In this section are the definitions of all of them to provide additional clarity.

Package link

The smallest set of files that are published to NPM and installed together, for example @angular/core . This package includes a manifest called package.json, compiled source code, typescript definition files, source maps, metadata, etc. The package is installed with npm install @angular/core .

Symbol link

A class, function, constant, or variable contained in a module and optionally made visible to the external world via a module export.

Module link

Short for ECMAScript Modules. A file containing statements that import and export symbols. This is identical to the definition of modules in the ECMAScript spec.

ESM link

Short for ECMAScript Modules (see above).

FESM link

Short for Flattened ES Modules and consists of a file format created by flattening all ES Modules accessible from an entry point into a single ES Module.

Module ID link

The identifier of a module used in the import statements (for example, @angular/core ). The ID often maps directly to a path on the filesystem, but this is not always the case due to various module resolution strategies.

Module specifier link

A module identifier (see above).

Module resolution strategy link

Algorithm used to convert Module IDs to paths on the filesystem. Node.js has one that is well specified and widely used, TypeScript supports several module resolution strategies, Closure Compiler has yet another strategy.

Module format link

Specification of the module syntax that covers at minimum the syntax for the importing and exporting from a file. Common module formats are CommonJS (CJS, typically used for Node.js applications) or ECMAScript Modules (ESM). The module format indicates only the packaging of the individual modules, but not the JavaScript language features used to make up the module content. Because of this, the Angular team often uses the language level specifier as a suffix to the module format, (for example, ESM+ES2015 specifies that the module is in ESM format and contains code down-leveled to ES2015).

Bundle link

An artifact in the form of a single JS file, produced by a build tool (for example, Webpack or Rollup) that contains symbols originating in one or more modules. Bundles are a browser-specific workaround that reduce network strain that would be caused if browsers were to start downloading hundreds if not tens of thousands of files. Node.js typically doesn't use bundles. Common bundle formats are UMD and System.register.

Language level link

The language of the code (ES2015 or ES2020). Independent of the module format.

Entry point link

A module intended to be imported by the user. It is referenced by a unique module ID and exports the public API referenced by that module ID. An example is @angular/core or @angular/core/testing . Both entry points exist in the @angular/core package, but they export different symbols. A package can have many entry points.

Deep import link

A process of retrieving symbols from modules that are not Entry Points. These module IDs are usually considered to be private APIs that can change over the lifetime of the project or while the bundle for the given package is being created.

Top-Level import link

An import coming from an entry point. The available top-level imports are what define the public API and are exposed in "@angular/name" modules, such as @angular/core or @angular/common .

Tree-shaking link

The process of identifying and removing code not used by an application - also known as dead code elimination. This is a global optimization performed at the application level using tools like Rollup, Closure Compiler, or Terser.

AOT compiler link

The Ahead of Time Compiler for Angular.

Flattened type definitions link

The bundled TypeScript definitions generated from API Extractor.

Animate state and style link

You can define a set of styles together to make up a specific state for animating elements and transitions. These states represent style at certain points in your animations that you can animate to and from. For example, you can animate a state as the starting point to a different state and the end of an animation.

What is a state? link

A state is the condition of an animation. The Angular state() function takes two parameters: a unique name and a style. There is also an optional parameter.

Why would you want to use state? link

Aliasing a set of styles and allows you to reference that alias for animations in general. This can make animations more readable or more understandable at a glance. You can give animations a useful and descriptive state name, which allows you to quickly understand the purpose of that animation state.

Use Angular's state() function to define different states to call at the end of each transition. This function takes two arguments: A unique name like open or closed and a style() function.

Use the style() function to define a set of styles to associate with a given state name. You must use camelCase for style attributes that contain dashes, such as backgroundColor or wrap them in quotes, such as 'background-color' .

Angular's state() function works with the style⁣­(⁠) function to set CSS style attributes. In this code snippet, multiple style attributes are set at the same time for the state. In the open state, the button has a height of 200 pixels, an opacity of 1, and a yellow background color.

      
        content_copy
      
      // ...
state('open', style({
  height: '200px',
  opacity: 1,
  backgroundColor: 'yellow'
})),
    

In the following closed state, the button has a height of 100 pixels, an opacity of 0.8, and a background color of blue.

      
        content_copy
      
      state('closed', style({
  height: '100px',
  opacity: 0.8,
  backgroundColor: 'blue'
})),
    

Animation API summary link

The functional API provided by the @angular/animations module provides a domain-specific language (DSL) for creating and controlling animations in Angular applications. See the API reference for a complete listing and syntax details of the core functions and related data structures.

Animation transition and timing link

An animation transition specifies changes that occur between one state and another. Set the transition to make the change less abrupt. An animation transition specifies the changes that occur between one state and another.

Animation transition() function defined link

The transition() function accepts two arguments:

An expression that defines the direction between two transition states An expression that accepts one or a series of animate() steps

Use the animate() function of a transition to define:

• Length
• Delay
• Easing
• Style function for defining styles while transitions are taking place

Use the animate() function to define the keyframes() function for multi-step animations. These definitions are placed in the second argument of the animate() function.

Animation metadata: duration, delay, and easing link

The animate() function accepts the timings and styles input parameters.

The timings parameter takes either a number or a string defined in three parts.

      
        content_copy
      
      animate (duration)
    

or

      
        content_copy
      
      animate ('duration delay easing')
    

The first part, duration , is required. The duration can be expressed in milliseconds as a number without quotes, or in seconds with quotes and a time specifier. For example, a duration of a tenth of a second can be expressed as follows:

• As a plain number, in milliseconds: 100

• In a string, as milliseconds: '100ms'

• In a string, as seconds: '0.1s'

The second argument, delay , has the same syntax as duration . For example:

• Wait for 100 ms and then run for 200 ms: '0.2s 100ms'

The third argument, easing , controls how the animation accelerates and decelerates during its runtime. For example, ease-in causes the animation to begin slowly, and to pick up speed as it progresses.

• Wait for 100 ms, run for 200 ms. Use a deceleration curve to start out fast and slowly decelerate to a resting point:

        
          content_copy
        
        0.2s 100ms ease-out
      

• Run for 200 ms, with no delay. Use a standard curve to start slow, speed up in the middle, and then decelerate slowly at the end:

        
          content_copy
        
        0.2s ease-in-out
      

• Start immediately, run for 200 ms. Use an acceleration curve to start slow and end at full velocity:

        
          content_copy
        
        
  The code sample is missing.
      

  0.2s ease-in

This example provides a state transition from open to closed with a 1-second transition between states.

      
        content_copy
      
      transition('open => closed', [
  animate('1s')
]),
    

In the preceding code snippet, the => operator indicates unidirectional transitions, and <=> is bidirectional. Within the transition, animate() specifies how long the transition takes. In this case, the state change from open to closed takes 1 second, expressed here as 1s .

This example adds a state transition from the closed state to the open state with a 0.5-second transition animation arc.

      
        content_copy
      
      transition('closed => open', [
  animate('0.5s')
]),