Web Animations API

declare const box: HTMLElement;
 
const anim = box.animate(
  [
    { transform: "translateY(8px)", opacity: 0 },
    { transform: "none", opacity: 1 },
  ],
  { duration: 300, easing: "ease-out", fill: "backwards" },
);
 
await anim.finished; // resolves when it ends

declare const el: HTMLElement;
 
// array of keyframes: one object per step
el.animate(
  [
    { opacity: 0, offset: 0 },
    { opacity: 1, offset: 0.7, easing: "ease-in" },
    { opacity: 0.5 }, // offset 1 inferred
  ],
  1000,
);
 
// property-indexed: one array per property
el.animate(
  {
    opacity: [0, 1],
    transform: ["scale(0.9)", "scale(1)"],
    easing: ["ease-out"], // per segment
  },
  1000,
);

declare const panel: HTMLElement;
 
const slide = panel.animate(
  [{ translate: "-100% 0" }, { translate: "0 0" }],
  { duration: 250, easing: "ease-out", fill: "both" },
);
slide.pause();
 
// scrub from a slider: 0..1
function scrub(t: number) {
  slide.currentTime = t * 250;
}
 
// toggle open/closed, even mid-flight
function toggle() {
  slide.reverse();
}
 
// cancel() rejects `finished`: swallow AbortError
slide.finished.then(
  () => panel.classList.add("open"),
  () => {},
);

declare const dialog: HTMLElement;
 
// wait for all animations (CSS ones included) to end
await Promise.allSettled(
  dialog
    .getAnimations({ subtree: true })
    .map((a) => a.finished),
);
 
// pause every CSS @keyframes animation called "spin"
for (const a of document.getAnimations()) {
  const isSpin =
    a instanceof CSSAnimation && a.animationName === "spin";
  if (isSpin) a.pause();
}

declare const card: HTMLElement;
 
const effect = new KeyframeEffect(
  card,
  [{ opacity: 0 }, { opacity: 1 }],
  { duration: 200, fill: "both" },
);
const anim = new Animation(effect, document.timeline);
anim.play();
 
effect.setKeyframes([{ opacity: 1 }, { opacity: 0 }]);
effect.updateTiming({ duration: 400 });
const t = effect.getComputedTiming();
t.progress;         // 0..1 within the iteration, or null
t.currentIteration; // number or null

declare const btn: HTMLElement;
 
// hover lift that stacks on top of any existing transform
btn.animate(
  { transform: ["translateY(0)", "translateY(-2px)"] },
  { duration: 150, fill: "forwards", composite: "add" },
);

declare const el: HTMLElement;
 
const a = el.animate(
  { transform: "translateX(200px)" },
  { duration: 300, fill: "forwards" },
);
await a.finished;
a.commitStyles(); // bake final value into el.style
a.cancel();       // release the fill

declare const bar: HTMLElement;
declare const card: HTMLElement;
 
// reading progress bar
bar.animate(
  { transform: ["scaleX(0)", "scaleX(1)"] },
  {
    timeline: new ScrollTimeline({
      source: document.documentElement,
      axis: "block",
    }),
    fill: "both",
  },
);
 
// fade in while the card enters the viewport
card.animate(
  { opacity: [0, 1], translate: ["0 40px", "0 0"] },
  {
    timeline: new ViewTimeline({ subject: card }),
    rangeStart: "entry 0%",
    rangeEnd: "entry 100%",
    fill: "both",
  },
);

type ScrollAxis = "block" | "inline" | "x" | "y";
 
interface ScrollTimelineOptions {
  source?: Element | null;
  axis?: ScrollAxis;
}
declare class ScrollTimeline extends AnimationTimeline {
  constructor(options?: ScrollTimelineOptions);
  readonly source: Element | null;
  readonly axis: ScrollAxis;
}
 
interface ViewTimelineOptions {
  subject?: Element | null;
  axis?: ScrollAxis;
  inset?: string | (string | CSSNumericValue)[];
}
declare class ViewTimeline extends ScrollTimeline {
  constructor(options?: ViewTimelineOptions);
  readonly subject: Element | null;
}
 
interface KeyframeAnimationOptions {
  rangeStart?: string | CSSNumericValue;
  rangeEnd?: string | CSSNumericValue;
}

const query = matchMedia("(prefers-reduced-motion: reduce)");
 
export function animateSafe(
  el: Element,
  frames: Keyframe[],
  opts: KeyframeAnimationOptions,
): Animation {
  if (!query.matches) return el.animate(frames, opts);
  // same end state, no motion
  return el.animate(frames, { ...opts, duration: 0 });
}
 
// react to the user flipping the setting
query.addEventListener("change", () => {
  if (query.matches) {
    document.getAnimations().forEach((a) => a.finish());
  }
});

export function flip(el: HTMLElement, mutate: () => void) {
  const first = el.getBoundingClientRect();
  mutate(); // change the DOM or classes
  const last = el.getBoundingClientRect();
  const dx = first.left - last.left;
  const dy = first.top - last.top;
  const sx = first.width / last.width;
  const sy = first.height / last.height;
  const from =
    `translate(${dx}px, ${dy}px) scale(${sx}, ${sy})`;
  return el.animate(
    [
      { transformOrigin: "top left", transform: from },
      { transformOrigin: "top left", transform: "none" },
    ],
    { duration: 300, easing: "ease-out" },
  );
}

export function stagger(
  items: Iterable<Element>,
  step = 40,
): Promise<Animation[]> {
  const anims = [...items].map((el, i) =>
    el.animate(
      [
        { opacity: 0, translate: "0 12px" },
        { opacity: 1, translate: "0 0" },
      ],
      {
        duration: 250,
        delay: i * step,
        easing: "ease-out",
        fill: "backwards",
      },
    ),
  );
  return Promise.all(anims.map((a) => a.finished));
}

declare const toast: HTMLElement;
 
async function showToast(ms = 3000) {
  const opts = { duration: 200, fill: "forwards" } as const;
  const enter = toast.animate(
    { opacity: [0, 1], translate: ["0 100%", "0 0"] },
    opts,
  );
  await enter.finished;
  await new Promise((r) => setTimeout(r, ms));
  const exit = toast.animate({ opacity: [1, 0] }, opts);
  await exit.finished;
  enter.cancel();
  exit.cancel();
  toast.hidden = true;
}

export function makeToggle(el: HTMLElement) {
  const anim = el.animate(
    [
      { opacity: 0, scale: "0.96" },
      { opacity: 1, scale: "1" },
    ],
    { duration: 180, easing: "ease-out", fill: "both" },
  );
  anim.pause();
  anim.currentTime = 0;
  let open = false;
  return () => {
    open = !open;
    anim.playbackRate = open ? 1 : -1;
    anim.play();
  };
}