feat(tabs): add the ability to customize the animation duration (#13505)

Adds the `animationDuration` input and the `MAT_TABS_CONFIG` injection token that can be used to configure the duration of the tab animation.

Fixes #13428.

Author: crisbeto

src/lib/tabs/tab-body.html

@@ -1,5 +1,8 @@
 <div class="mat-tab-body-content" #content
-     [@translateTab]="_position"
+     [@translateTab]="{
+        value: _position,
+        params: {animationDuration: animationDuration}
+     }"
      (@translateTab.start)="_onTranslateTabStarted($event)"
      (@translateTab.done)="_onTranslateTabComplete($event)">
   <ng-template matTabBodyHost></ng-template>

src/lib/tabs/tab-body.ts

@@ -146,6 +146,11 @@ export class MatTabBody implements OnInit, OnDestroy {
   /** Position that will be used when the tab is immediately becoming visible after creation. */
   @Input() origin: number;
 
+  // Note that the default value will always be overwritten by `MatTabBody`, but we need one
+  // anyway to prevent the animations module from throwing an error if the body is used on its own.
+  /** Duration for the tab's animation. */
+  @Input() animationDuration: string = '500ms';
+
   /** The shifted index position of the tab body, where zero represents the active center tab. */
   @Input()
   set position(position: number) {

src/lib/tabs/tab-group.html

@@ -40,6 +40,7 @@
                [content]="tab.content"
                [position]="tab.position"
                [origin]="tab.origin"
+               [animationDuration]="animationDuration"
                (_onCentered)="_removeTabBodyWrapperHeight()"
                (_onCentering)="_setTabBodyWrapperHeight($event)">
   </mat-tab-body>

src/lib/tabs/tab-group.ts

@@ -22,6 +22,9 @@ import {
   QueryList,
   ViewChild,
   ViewEncapsulation,
+  InjectionToken,
+  Inject,
+  Optional,
 } from '@angular/core';
 import {
   CanColor,
@@ -51,6 +54,15 @@ export class MatTabChangeEvent {
 /** Possible positions for the tab header. */
 export type MatTabHeaderPosition = 'above' | 'below';
 
+/** Object that can be used to configure the default options for the tabs module. */
+export interface MatTabsConfig {
+  /** Duration for the tab animation. Must be a valid CSS value (e.g. 600ms). */
+  animationDuration?: string;
+}
+
+/** Injection token that can be used to provide the default options the tabs module. */
+export const MAT_TABS_CONFIG = new InjectionToken('MAT_TABS_CONFIG');
+
 // Boilerplate for applying mixins to MatTabGroup.
 /** @docs-private */
 export class MatTabGroupBase {
@@ -117,6 +129,9 @@ export class MatTabGroup extends _MatTabGroupMixinBase implements AfterContentIn
   /** Position of the tab header. */
   @Input() headerPosition: MatTabHeaderPosition = 'above';
 
+  /** Duration for the tab animation. Must be a valid CSS value (e.g. 600ms). */
+  @Input() animationDuration: string;
+
   /** Background color of the tab group. */
   @Input()
   get backgroundColor(): ThemePalette { return this._backgroundColor; }
@@ -150,9 +165,12 @@ export class MatTabGroup extends _MatTabGroupMixinBase implements AfterContentIn
   private _groupId: number;
 
   constructor(elementRef: ElementRef,
-              private _changeDetectorRef: ChangeDetectorRef) {
+              private _changeDetectorRef: ChangeDetectorRef,
+              @Inject(MAT_TABS_CONFIG) @Optional() defaultConfig?: MatTabsConfig) {
     super(elementRef);
     this._groupId = nextId++;
+    this.animationDuration = defaultConfig && defaultConfig.animationDuration ?
+        defaultConfig.animationDuration : '500ms';
   }
 
   /**

src/lib/tabs/tabs-animations.ts

@@ -34,14 +34,14 @@ export const matTabsAnimations: {
     state('right', style({transform: 'translate3d(100%, 0, 0)', minHeight: '1px'})),
 
     transition('* => left, * => right, left => center, right => center',
-        animate('500ms cubic-bezier(0.35, 0, 0.25, 1)')),
+        animate('{{animationDuration}} cubic-bezier(0.35, 0, 0.25, 1)')),
     transition('void => left-origin-center', [
       style({transform: 'translate3d(-100%, 0, 0)'}),
-      animate('500ms cubic-bezier(0.35, 0, 0.25, 1)')
+      animate('{{animationDuration}} cubic-bezier(0.35, 0, 0.25, 1)')
     ]),
     transition('void => right-origin-center', [
       style({transform: 'translate3d(100%, 0, 0)'}),
-      animate('500ms cubic-bezier(0.35, 0, 0.25, 1)')
+      animate('{{animationDuration}} cubic-bezier(0.35, 0, 0.25, 1)')
     ])
   ])
 };

src/lib/tabs/tabs.md

@@ -114,6 +114,13 @@ do so using the `[mat-align-tabs]` attribute.
 
 <!-- example(tab-group-align) -->
 
+### Controlling the tab animation
+You can control the duration of the tabs' animation using the `animationDuration` input. If you
+want to disable the animation completely, you can do so by setting the properties to `0ms`. The
+duration can be configured globally using the `MAT_TABS_CONFIG` injection token.
+
+<!-- example(tab-group-animations) -->
+
 ### Accessibility
 Tabs without text or labels should be given a meaningful label via `aria-label` or
 `aria-labelledby`. For `MatTabNav`, the `<nav>` element should have a label as well.

src/material-examples/tab-group-animations/tab-group-animations-example.css

@@ -0,0 +1,3 @@
+.mat-tab-group {
+  margin-bottom: 48px;
+}

src/material-examples/tab-group-animations/tab-group-animations-example.html

@@ -0,0 +1,14 @@
+<h3>No animation</h3>
+
+<mat-tab-group animationDuration="0ms">
+  <mat-tab label="First">Content 1</mat-tab>
+  <mat-tab label="Second">Content 2</mat-tab>
+  <mat-tab label="Third">Content 3</mat-tab>
+</mat-tab-group>
+
+<h3>Very slow animation</h3>
+<mat-tab-group animationDuration="2000ms">
+  <mat-tab label="First">Content 1</mat-tab>
+  <mat-tab label="Second">Content 2</mat-tab>
+  <mat-tab label="Third">Content 3</mat-tab>
+</mat-tab-group>

src/material-examples/tab-group-animations/tab-group-animations-example.ts

@@ -0,0 +1,11 @@
+import {Component} from '@angular/core';
+
+/**
+ * @title Tab group animations
+ */
+@Component({
+  selector: 'tab-group-animations-example',
+  templateUrl: 'tab-group-animations-example.html',
+  styleUrls: ['tab-group-animations-example.css'],
+})
+export class TabGroupAnimationsExample {}