README.md

ngx-easy-view-transitions

Angular library for easier use of the View Transitions API

Demo

https://derstimmler.github.io/ngx-easy-view-transitions/

Installation

Available on npm.

npm install ngx-easy-view-transitions

You have to enable Angulars built-in view transitions in the Router using the withViewTransitions() function.

bootstrapApplication(AppComponent,
  {
    providers: [
      provideRouter(appRoutes, withViewTransitions())
    ]
  }
);

Usage

Morph elements

To morph an element during navigation from the old to the new state use the transitionName directive and provide the same name on both pages.

import { TransitionNameDirective } from 'ngx-easy-view-transitions';

users.component.html

<img transitionName="profile-picture" src="...">

user.component.html

<img transitionName="profile-picture" src="...">

Note that each transitionName must be unique for a page.

Customize animations

Instead of morphing an element, you can provide custom animations for entering and leaving the view using the inAnimation and outAnimation inputs. There are two ways to provide a custom animations: As CSS @keyframes rule or Keyframe array.

Using CSS @keyframes

You can simply use a CSS @keyframes rule from your CSS:

@keyframes fadeIn {
  from {
    opacity: 0;
  }

  to {
    opacity: 1;
  }
}

inAnimation = { keyframeName: 'fadeIn', duration: 600 };
outAnimation = { keyframeName: 'fadeIn', duration: 600, reverse: true };

<img transitionName="profile-picture" [inAnimation]="inAnimation" [outAnimation]="outAnimation" src="...">

Using Keyframe array

When you want to use typed objects instead of CSS you can provide a Keyframe array:

const fadeIn: Keyframe[] = [
  {
    opacity: 0,
    offset: 0,
  },
  {
    opacity: 1,
    offset: 1,
  },
];

inAnimation = { keyframes: fadeIn, duration: 600 };
outAnimation = { keyframes: fadeIn, duration: 600, reverse: true };

<img transitionName="profile-picture" [inAnimation]="inAnimation" [outAnimation]="outAnimation" src="...">

Built-In animations

To start faster there are some built-in animations available under DefaultTransitions.*.

import { DefaultTransitions } from 'ngx-easy-view-transitions';

inAnimation = { keyframes: DefaultTransitions.fadeInUp, duration: 600 };

You can see them in the demo and here.

Exclude element from view transitions

When you want to exclude an element form view transitions you can add the noTransition directive.

import { NoTransitionDirective } from 'ngx-easy-view-transitions';

<img noTransition src="...">

Configure default transition

By default View Transitions API will perform a cross-fade animation on all elements. But you can also provide your own in and out animations by adding the provideDefaultViewTransition() provider function.

In the following example the default animation gets disabled:

bootstrapApplication(AppComponent,
  {
    providers: [
      provideRouter(appRoutes, withViewTransitions()),
      provideDefaultViewTransition(
        { keyframes: DefaultTransitions.none, duration: 0 },
        { keyframes: DefaultTransitions.none, duration: 0 }
      )
    ]
  }
);

Development

Install dependencies with: pnpm install

Run pnpm demo to run the demo app on a local development server. You can access it on http://localhost:4200.

Run pnpm test to test all projects.

Run pnpm lint to lint all projects.

Run pnpm build to build all projects. You can find the output under /dist.

Since it's a nx workspace you can use the common nx commands for everything else.