@lit-labs/motion

Lit directives for making things move.

[!WARNING]

This package is part of Lit Labs. It is published in order to get feedback on the design and may receive breaking changes or stop being supported.

Please read our Lit Labs documentation before using this library in production.

Give feedback: https://github.com/lit/lit/discussions/3351

Installation

From inside your project folder, run:

$ npm install @lit-labs/motion

Animate directive

The animate directive can be used to animate DOM elements from one lit render to the next. If the animate element changes state between renders, the directive performs a "tweening" animation between the two states based on the options given. In addition, elements can animate when they initially render to DOM and when they are removed.

The directive supports a number of options:

How it works

The directive uses the FLIP animation technique--derived from First, Last, Invert, Play. This describes how the directive works. It measures the styling of the animate element before a layout change (first) and after a layout change (last). Then it inverts the last layout such that it matches the first layout. Finally it plays an animation which removes the inverted layout such that the element animates to the "last" layout. See the FLIP article by Paul Lewis for more information about the technique.

The directive uses a reactive controller to coordinate measuring the DOM of the animate element. The first layout is measured when the hosting element updates, and the last layout is measured when the hosting element renders and completes its update.

Usage

Here's an example:

import {animate} from '@lit-labs/motion';
// ...

class MyElement extends LitElement {
  static properties = {shifted: {}};
  static styles = css`
    .box {
      position: absolute;
      width: 100px;
      height: 100px;
      background: steelblue;
      top: 100px;
      border-radius: 50%;
    }

    .shifted {
      right: 0;
    }
  `;

  render() {
    return html`
      <button @click=${this._toggle}>Move</button>
      <div class="box ${this.shifted ? 'shifted' : ''}" ${animate()}></div>
    `;
  }

  _toggle() {
    this.shifted = !this.shifted;
  }
}

AnimateController

The animate controller allows you to coordinate and control animate directives within a given element.

The controller constructor takes an options object with the following properties:

The animate controller also provides API for controlling animate animations, including play(), pause(), cancel(), finish(), and togglePlay(). These methods affect all the animate animations for a given element. Finally, animate controller has properties which reflect the state of the animate animations in the host element: isPlaying returns true if any animate's are currently playing; isAnimating returns true if any animates currently have animations (which may be paused).

Spring and Spring2D controllers

The Spring and Spring2D controllers simulate physical springs with the Wobble library.

To use a spring you set the fromPosition and toPosition properties, which puts the spring into tension, and the end of the spring into motion. currentPosition will update of the course of the spring simulation, and the spring controller will trigger an element update so that the element can read currentPosition and render using it.

import {SpringController2D} from '@lit-labs/motion/spring.js';

@customElement('goo-element')
export class GooElement extends LitElement {
  // Both the MouseController and SpringController2D will
  // trigger a render when the mouse moves or the spring updates
  #mouse = new MouseController(this);
  #spring = new SpringController2D(this, fast);

  render() {
    // Set the spring to go to the mouse
    this.#spring.toPosition = this.#mouse.position;

    // Position a div based on the current position of the spring.
    return html`
      <div
        class="b1"
        style=${positionStyle(this.#spring.currentPosition)}
      ></div>
    `;
  }
}

const fast = {
  stiffness: 1200,
  damping: 400,
};

const positionStyle = ({x, y}: Position2D) =>
  styleMap({
    transform: `translate3d(${x}px,${y}px,0) translate3d(-50%,-50%,0)`,
  });

Configuration

The SpringController constructor takes the host element and a SpringConfig object with the following properties:

The SpringController2D constructor's Spring2DConfig has the same properties except fromValue, toValue, and initialVelocity, which are replaced with 2D equivalents:

Contributing

Please see CONTRIBUTING.md.