Enter and exit

enter(el, preset) and exit(el, preset) return promises, so a component can await an exit before removing or hiding the element.

import { enter, exit } from '@ds-gn/motion';

panel.hidden = false;
await enter(panel, 'scaleIn');

await exit(panel, 'scaleIn');
panel.hidden = true;

An exit holds its hidden end state until you remove or hide the element, or play it back in. Calling the opposite direction mid-animation reverses from the current position, over the share of the duration it has travelled, and the interrupted promise still resolves. Calling the same direction again returns the promise already in flight.

Both accept duration, easing, delay, and reducedMotion. cancel(targets) stops whatever is animating, including a held exit, and resolves its promise.

Viewport trigger

inView(el, callback, options) runs the callback when the element enters the viewport, once by default. It returns a function that stops observing. Where IntersectionObserver is unavailable, the callback runs immediately.

import { inView, sequence } from '@ds-gn/motion';

inView(section, () => sequence(cards, { preset: 'fade', stagger: 40 }), {
  rootMargin: '0px 0px -10% 0px',
});

Pass once: false to run on every entry. root, rootMargin, and threshold are forwarded to the observer.

inView is for starting motion when something appears. For ongoing on-screen state, such as pausing a timer while a section is offscreen, use an IntersectionObserver directly or Lit’s IntersectionController.

Dialog backdrops and pseudo-elements

Pass pseudoElement to animate a pseudo-element independently of its element:

await Promise.all([
  exit(dialog, 'slideInLeft'),
  exit(dialog, 'fade', { pseudoElement: '::backdrop' }),
]);
dialog.close();

The option also works on timeline steps, sequences, and controller calls. Tracks are separate for each element/pseudo-element pair; reversing a backdrop reads its own computed style. cancel(dialog) cancels all of its tracks, including held exits on the backdrop. Timings resolve from the dialog’s motion custom properties. Exit easing defaults to standard.

Pseudo-element animation is supported in Chrome 84+, Firefox 75+, and Safari 14+ (MDN compatibility data). Native modal dialogs require Safari 15.4+.