@tooark/motion

Opt-in animation helpers on the Motion library, calibrated by the Tooark motion tokens: staggered entrances, scroll reveal, FLIP reordering and swipe gestures with spring physics.

🌍 Languages: English (this file) · Português

Contents

• Overview
• Installation
• Configuration
• Components
• Usage examples
• Dependencies
• Contributing
• License

📖 Overview

The @tooark/motion package provides:

• arkStaggerEnter(targets, options): entrance of a list with the fade/slide-*/scale presets, interval and from (first, last, center);
• arkReveal(targets, options): enter animation when the elements scroll into view (once, amount, margin), returns a stop function;
• arkFlip(targets, mutate, options): measure, apply your DOM mutation (reorder, insert, filter) and animate each item to its new place with a spring (stiffness, damping);
• arkSwipe(element, options): pointer gesture on an axis with threshold, velocityThreshold, drag feedback and resistance, calling onSwipe(direction, { delta, velocity });
• every helper honors prefers-reduced-motion; arkStaggerEnter and arkReveal also read the --ark-duration-*/--ark-ease-*/--ark-motion-distance tokens (arkFlip and arkSwipe animate with springs, not token durations or easings); the Motion primitives (animate, spring, stagger, inView, …) are re-exported;
• nothing here is required by the components: @tooark/core already ships a dependency-free motion layer.

🔧 Installation

pnpm add @tooark/motion   # brings motion, @tooark/core and @tooark/tokens

⚙️ Configuration

No registration: import the helpers you use. The durations, easings and slide distance of arkStaggerEnter/arkReveal come from the tokens on the page (@tooark/web-components/styles.css or @tooark/core/styles.css); without them the JS mirrors apply (durations and distance from @tooark/tokens, curves from the package's own bezier table).

📦 Components

• arkStaggerEnter(targets, { preset?, duration?, ease?, distance?, interval?, from? }) → Promise<void>.
• arkReveal(targets, { preset?, duration?, ease?, distance?, once?, amount?, margin? }) → stop function.
• arkFlip(targets, mutate, { stiffness?, damping? }) → Promise<void>.
• arkSwipe(element, { axis?, threshold?, velocityThreshold?, feedback?, resistance?, onSwipe }) → dispose function.
• targets: a selector, an element, an array or a NodeList (ArkMotionTargets).
• Re-exports from Motion: animate, hover, inView, press, scroll, spring, stagger.
• Types: ArkMotionPlusOptions, ArkStaggerOptions, ArkRevealOptions, ArkFlipOptions, ArkSwipeOptions, ArkSwipeDirection, ArkSwipeInfo, ArkMotionPreset, ArkMotionTargets.

📝 Usage examples

Staggered list entrance and scroll reveal

import { arkReveal, arkStaggerEnter } from "@tooark/motion";

await arkStaggerEnter(".results > li", { preset: "slide-up", interval: 40, from: "first" });

const stop = arkReveal(".card", { preset: "fade", once: true, amount: 0.3 });
// on teardown: stop();

FLIP reordering and a swipe-to-dismiss row

import { arkFlip, arkSwipe } from "@tooark/motion";

const list = document.querySelector("ul")!;
await arkFlip(Array.from(list.children), () => {
  list.prepend(list.lastElementChild!); // any DOM mutation: reorder, insert, filter
});

const dispose = arkSwipe(row, {
  axis: "x",
  threshold: 64,
  onSwipe: (direction) => {
    if (direction === "left") archive(row);
  },
});

In React, Vue and Angular

The helpers are plain functions, so no wrapper is needed: call them after the elements exist and call the returned stop/dispose function when the component goes away. Pass elements from a ref rather than a selector, since a selector searches the whole document and would also animate other instances of the component.

// React
useEffect(() => arkReveal(listRef.current!.querySelectorAll(":scope > li"), { preset: "fade", once: true }), []);

// Vue
let stop = () => {};
onMounted(() => (stop = arkSwipe(row.value!, { axis: "x", onSwipe: archive })));
onBeforeUnmount(() => stop());

// Angular
ngAfterViewInit(): void {
  this.stop = arkReveal(this.list.nativeElement.querySelectorAll(":scope > li"), { preset: "fade" });
}
ngOnDestroy(): void {
  this.stop?.();
}

📋 Dependencies

Installed automatically unless marked as peer; peer dependencies are yours to install (the ranges are what the package declares).

| Package | Version | Description | | ---------------------------------------------------------------- | ------- | ---------------------------------------------------------------- | | @tooark/core | ^1.3.0 | Types, i18n, toast/announce services, motion and overlay helpers | | @tooark/tokens | ^1.3.0 | Design tokens (colors, sizes, motion) and primitive types | | motion | ^13.4.4 | Motion animation library (spring physics, scroll, gestures) | | tslib | ^2.8.1 | TypeScript runtime helpers |

🪪 Contributing

Contributions are welcome! Open issues and pull requests in the Tooark/web-components repository; CONTRIBUTING.md covers the workflow, the commit convention and the checklist. @tooark/motion is released in lockstep with every other @tooark/* package.

📄 License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.