Neurotic and Probably Misinformed

    TypeScript icon, indicating that this package has built-in type declarations

    0.1.1 • Public • Published

    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


    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.


    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 {
    } 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$` 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$` and `willChange$`.
    // `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,
    // Now, we assign the class name that JSS generated to the element that we
    // received the pointer events from:

    You can see this in action at The source code is in TossableDemo.


    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:

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


    yarn add material-motion


    Apache 2.0


    npm i material-motion

    DownloadsWeekly Downloads






    Unpacked Size

    9.4 MB

    Total Files


    Last publish


    • appsforartists