material-motion

Makes it easy to add rich, interactive motion to your application.

Usage no npm install needed!

<script type="module">
  import materialMotion from 'https://cdn.skypack.dev/material-motion';
</script>

README

logo Material Motion

Material Motion is a library used by the Material Design team to prototype interactive experiences with gestures.

Current version: Test status Code coverage
HEAD: Test status Code coverage

Chat

Status: Experimental

🚨 Material Motion has not been used in a production application at Google. It is unstable and unsupported. 🚨

Unexplored areas

  • bundle size

    Material Motion has not been run through Closure Compiler. No attempts have been made to minify its file size.

    Operators are presently implemented using the mixin pattern, which may not minify well. We may migrate to a pipeable architecture, like RxJS's, in a future version.

  • memory footprint

    Interactions are implemented by composing streams of user input to emit styles like transform and opacity. We have not yet explored when/how these streams should be freed for garbage collection.

Other likely changes

  • function signatures

    Material Motion uses the named argument pattern to make it easier to evolve APIs without making breaking changes. There is usually a positional shorthand. For instance, these are equivalent:

    openOffset$.addedBy({ value$: thresholdAmount$ })  // named argument
    
    openOffset$.addedBy(thresholdAmount$)              // positional shorthand
    
    openOffset$.addedBy({                              // named argument, with
      value$: thresholdAmount$,                        // an explicit value for
      onlyEmitWithUpstream: false,                     // an optional parameter
    })
    

    All arguments that accept stream values are suffixed with $.

    The Material Motion API is declarative. Its operators accept literal values and other streams, but not functions. This decision was made to ensure the API is portable across platforms, and to provide a foundation for visual tooling to be built on top of.

    We will continue to assess the impact of these patterns on both ergonomics and code size, and may make changes in the future accordingly.

Usage

Material Motion is often used to implement the toss gesture: where the user drags an element, and when it's released, it springs to a resting position. Tossable observes the drag's velocity and passes it to the spring, preserving the user's momentum and making the interaction feel seamless.

Here's a simple example:

// We use JSS to update the document's style sheet whenever Material Motion
// emits a new value.
import { create as createJSS } from 'jss';
import createDefaultJSSPreset from 'jss-preset-default';

import {
  Draggable,
  Point2DSpring,
  Tossable,
  combineStyleStreams,
  getPointerEventStreamsFromElement,
} from 'material-motion';

// We're presuming there's an element on the page called "ball" that we want to
// make tossable.
const ball = document.getElementById('ball');

// `Draggable` listens for events on the down, move, and up streams.  It
// calculates how far a pointer has been dragged, and emits the result on its
// `value

	
		
		
		
		
		
		
		
	npm:material-motion | Skypack
	
		
		
		
		 stream.
const pointerEvents = getPointerEventStreamsFromElement(ball);
const draggable = new Draggable(pointerEvents);

// `Tossable` passes the velocity from `draggable` into the spring.  This
// ensures that when the user lets go, the item continues moving at the same
// speed it was while the user was in control.
const spring = new Point2DSpring();
const tossable = new Tossable({ draggable, spring });

// `Tossable` outputs `translate

	
		
		
		
		
		
		
		
	npm:material-motion | Skypack
	
		
		
		
		 and `willChange

	
		
		
		
		
		
		
		
	npm:material-motion | Skypack
	
		
		
		
		.
//
// `combineStyleStreams` will combine these into a stream of
// `{ transform, willChange }`, to be passed to JSS.
const ballStyles$ = combineStyleStreams(tossable.styleStreams);

// Unfortunately, there's a bit of boilerplate to instantiate JSS.  Notice
// that the output of `tossable` has been given the name `ball` here.
const styleSheet = jss.createStyleSheet(
  {
    ball: ballStyles$,
  },
  {
    link: true,
  }
).attach();

// Now, we assign the class name that JSS generated to the element that we
// received the pointer events from:
ball.classList.add(styleSheet.classes.ball);

You can see this in action at https://material-motion-demos.firebaseapp.com/toss/. The source code is in TossableDemo.

Documentation

Material Motion was originally a cross-platform initiative that targeted Android, iOS, and the Web. Although the other platforms are not currently in active development, you may find the documentation from the shared project helpful: https://material-motion.github.io/material-motion/documentation/

Unfortunately, there is not yet independent documentation for the JavaScript implementation. Hopefully, there will be in there future.

Installation

yarn add material-motion

License

Apache 2.0