ngx-easy-view-transitions 3.1.2 → 3.3.0

package/README.md

@@ -20,23 +20,19 @@ npm install ngx-easy-view-transitions
 
 Required Angular version: `>=19.0.0`
 
-You have to enable Angulars built-in view transitions in the Router using the [`withViewTransitions()`](https://angular.io/api/router/withViewTransitions#usage-notes) function.
+You have to enable Angular's built-in view transitions in the Router using the [`withViewTransitions()`](https://angular.io/api/router/withViewTransitions#usage-notes) function.
 
 ```typescript
-bootstrapApplication(AppComponent,
-  {
-    providers: [
-      provideRouter(appRoutes, withViewTransitions())
-    ]
-  }
-);
+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.
+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.
 
 ```typescript
 import { TransitionNameDirective } from 'ngx-easy-view-transitions';
@@ -56,6 +52,13 @@ import { TransitionNameDirective } from 'ngx-easy-view-transitions';
 
 Note that each `transitionName` must be unique for a page.
 
+Transition names must be valid [`<custom-ident>`](https://developer.mozilla.org/en-US/docs/Web/CSS/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.
@@ -88,18 +91,18 @@ outAnimation = { keyframeName: 'fadeIn', duration: 600, reverse: true };
 
 #### Using Keyframe array
 
-When you want to use typed objects instead of CSS you can provide a [`Keyframe`](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API/Keyframe_Formats) array:
+When you want to use typed objects instead of CSS, you can provide a [`Keyframe`](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API/Keyframe_Formats) array:
 
 ```typescript
 const fadeIn: Keyframe[] = [
   {
     opacity: 0,
-    offset: 0,
+    offset: 0
   },
   {
     opacity: 1,
-    offset: 1,
-  },
+    offset: 1
+  }
 ];
 ```
 
@@ -112,9 +115,26 @@ 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](https://developer.mozilla.org/de/docs/Web/CSS/Reference/Properties/animation),
+such as `fill-mode`, `delay`, or `timing-function`.
+
+```ts
+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.*`.
+To start faster, there are some built-in animations available under `DefaultTransitions.*`.
 
 ```typescript
 import { DefaultTransitions } from 'ngx-easy-view-transitions';
@@ -122,7 +142,7 @@ import { DefaultTransitions } from 'ngx-easy-view-transitions';
 inAnimation = { keyframes: DefaultTransitions.fadeInUp, duration: 600 };
 ```
 
-You can see them in the [demo](https://derstimmler.github.io/ngx-easy-view-transitions/animations) and [here](https://github.com/DerStimmler/ngx-easy-view-transitions/blob/main/ngx-easy-view-transitions/src/lib/default-transitions.ts).
+You can check them out in the [demo](https://derstimmler.github.io/ngx-easy-view-transitions/animations) and [here](https://github.com/DerStimmler/ngx-easy-view-transitions/blob/main/ngx-easy-view-transitions/src/lib/default-transitions.ts).
 
 ### Exclude element from view transitions
 
@@ -143,19 +163,25 @@ But you can also provide your own in and out animations by adding the `provideDe
 
 In the following example, the default animation gets disabled:
 
+<!-- prettier-ignore-start -->
 ```typescript
 bootstrapApplication(AppComponent,
   {
     providers: [
       provideRouter(appRoutes, withViewTransitions()),
       provideDefaultViewTransition(
-        { keyframes: DefaultTransitions.none, duration: 0 },
-        { keyframes: DefaultTransitions.none, duration: 0 }
+        {keyframes: DefaultTransitions.none, duration: 0},
+        {keyframes: DefaultTransitions.none, duration: 0}
       )
     ]
   }
 );
 ```
+<!-- prettier-ignore-end -->
+
+### Troubleshooting
+
+If your elements flicker when navigating, try to set the `fillMode` to `forwards`.
 
 ## Development