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

Required Angular version: >=19.0.0

You have to enable Angular's 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.

Transition names must be valid <custom-ident>. This library helps with this, by hashing the name to automatically comply.

For debugging purposes, you can show the original provided value as data-original-view-transition-name attribute by setting showOriginalNameAttr to true.

To opt out of hashing, set preserveName to true.

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="...">

Further customization

You can further customize the animation by passing standard CSS animation properties, such as fill-mode, delay, or timing-function.

animation = {
  keyframeName: 'fadeIn',
  duration: 600,
  reverse: true,
  fillMode: 'forwards',
  timingFunction: 'ease-in',
  delay: 100
};

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 check them out in the demo and here.

Exclude element from view transitions

When you want to exclude an element from 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}
      )
    ]
  }
);

Troubleshooting

If your elements flicker when navigating, try to set the fillMode to forwards.

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.