Utilities to support the View Transitions API in Ember apps
npm install @cardstack/view-transitionsEmber utilities for triggering native View Transition API animations.
- Ember.js v5.8 or above
- Embroider or ember-auto-import v2
``
ember install @cardstack/view-transitions
You will need to learn about the View Transition API to make use of this library. This library provides some small utilities that make it convenient to use View Transitions in Ember apps.
`ts
export function animatable
initialValue: T,
opts?: { equals?: (a: T, b: T) => boolean },
): Animatable
export interface Animatable
readonly current: T;
set(newValue: T): void;
}
`
Creates a value that triggers a ViewTransition whenever it changes. current does not update instantly when you call set, instead current is allowed to update after the ViewTransition has already snapshotted the "before" state for the View Transition.
`gts
import { animatable } from '@cardstack/view-transitions';
const expanded = animatable(false);
function toggleExpanded() {
expanded.set(!expanded.current);
}
{{#if expanded.current}}
{{else}}
{{/if}}
`
Animatable values are also necessarily tracked, for full interoperability with the rest of Ember. You can consume them like any other tracked state, and re-renders will happen automatically, with the added bonus that the DOM state before and after the re-render will be captured by the browser and can be smoothly animated.
A modifier that sets the view-transition-name CSS property. Useful for programmatically assigning unique names based on model IDs, etc. Accepts any number of strings or numbers and concatenates them to form the view-transition-name.
`ts`
viewTransitionName: FunctionBasedModifier<{
Args: {
Positional: (string | number)[];
};
Element: HTMLElement;
}>;
`gts`
import { viewTransitionName } from '@cardstack/view-transitions';
{{#each @products as |product|}}
{{product.title}}
{{/each}}
The critical thing to understand about the view-transition-name CSS property is that it must be unique on the whole page. It can appear in both the "old" and "new" states of the DOM, but can't appear simultaneously more than once. It controls which elements get captured (think: "screenshotted") during the ViewTransition, and how the old and new element correlate.
This repo contains a demo app. To run it:
`sh``
pnpm install
pnpm start
See the Contributing guide for details.
This project is licensed under the MIT License.