npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

el-animate

v1.3.0

Published

Easily animate html elements using css and control it with js

Downloads

17

Readme

ELAnimate

NPM Package Minified Size Gzipped Size Tree-shakeable Types included

ElAnimate is a small, lightweight, cross-browser TypeScript library-helper, that helpes to create simple HTML-element animations described in CSS with transition or animation property, but controlled in JavaScipt by changing classNames. This combination allows creating hardware accelerated native css animations with best performance and smoothness on the one hand, but provides simplicity and convenience on the other hand.

This library is also very useful for enter/leave animations. Without this library it is very hard to animate element first and only then delete it from DOM (for example, animated burger menu, or backdrop).

Note: this library is intended for simple animations from one point to another. If you want to create complicated animations with different timings or something like this, you should use libraries where you describe and controll everything in in JavaScript.

Features

  • Lightweight: ~1.5KB minified & gziped
  • Simple: ElAnimate exports only animate and cancelAnimation functions, has a few config options
  • Fully typed: This package is written in TypeScript, every config option has type, and JSDoc annotations
  • Library Independent: ElAnimate has no dependences and doesn't require any library like JQuery

Demos

Installation

Package manager

The most common is npm:

npm install el-animate --save

Alternatively you can use yarn:

yarn add el-animate

CDN, Local installation

You can use either CDN like JSDELIVR, UNPKG or you can directly download el-animate.iife.js from CDN, and insert el-animate from your local copy. Main thing is to place el-animate before your other scripts. For example:

<script src="https://cdn.jsdelivr.net/npm/el-animate/dist/el-animate.iife.js"></script>
<!-- Then your scripts -->
<script>
  ElAnimate.animate(elem, config);
</script>

Importing

ESM

import { animate, cancelAnimation } from 'el-animate';
// or, if you don't need 'cancelAnimation' function:
import animate from 'el-animate';

CommonJS

const ElAnimate = require('el-animate');

Usage

If you khow how to improve usage guide, please write an issues or open a new pull request

Main function for animating html element looks like this:

ElAnimate.animate(elem: HTMLElement, config: Config);

Main idea is to change 5 classnames of HTML-element at the right time. In this classes you should write styles (demo):

How el-animate works

To reproduce this animation, in active classname you should write transition or animation property, in from classname you should write from which point animation should start and in initial classname you should write display: none

We strongly recommend you to use css properties like transform or opacity for animations, which do not trigger expensive CSS layout calculation in comparison to properties like height or margin. For checking which property is recommended to use, see CSS-Triggers

.elem {
  opacity: 1;
}

.elem-initial {
  display: none;
}

.elem-from {
  opacity: 0;
}

.elem-active {
  transition: opacity 0.5s ease;
}

And then of course you should configure classnames and other parameters in JavaScipt

Full list of parameters:

{
  classNames: {
    /**
     * If you specify prefix, all classnames except `final` will automatically be generated with this prefix.
     * *You can overwrite any prefixed classname, if you specify it (including that case, when you specify empty classname).*
     * @example
     * prefix: 'animation',
     * classnames.initial: 'animation-initial',
     * classnames.from: 'animation-from'...
     * @default
     * undefined
     */
    prefix: string;
    /**
     * ClassName which element contains before animation starts and should be deleted when animation starts
     * @default ''
     */
    initial: string;
    /**
     * From wich point animation should be started
     * (Adds: 1st frame, Removes: 2nd frame)
     * @default ''
     */
    from: string;
    /**
     * ClassName which element contains during the whole animation.
     * Usually there you write `animation` or `transition` css properties.
     * (on: 1st frame, off: last frame)
     * @default ''
     */
    active: string;
    /**
     * Final animation point. Note: If you want the element to have `to` state after animation end, then set `final` classname the same as `to`
     * (on: 2nd frame, off: last frame)
     * @default ''
     */
    to: string;
    /**
     * ClassName which element contains after animation ends
     * @default ''
     */
    final: string;
  };
  /**
   * This property is necessary for correct animation end detecting
   */
  animation: {
    /**
     * When you add animations with css, you can do this either with `transition` or with `animation` property
     * You should choose one of this for correct animation end detecting if you have problems.
     * By default ElAnimate adds both `transitionend` and `animationend` handlers
     * As a last resort, you can set `animation.name`
     * @default 'both'
     */
    type: 'transition' | 'animation' | 'both';
    /**
     * if you have several animation, you can additionally set `animation.name` field in config
     * Then ElAnimate can properly detect animation end with this animation name.
     * You should type the same string as in @keyframes
     */
    name: string | undefined;
  };
  callbacks: {
    /**
     * Called before animation start, element has `initial` classname
     */
    beforeStart: (elem: HTMLElement, currentConfig: Config) => void;
    /**
     * Called when animation initialized: element has `from` classname, animation end handling added
     */
    fromStateSet: (elem: HTMLElement, currentConfig: Config) => void;
    /**
     * Called when element has `to` classname
     */
    toStateSet: (elem: HTMLElement, currentConfig: Config) => void;
    /**
     * Called when animation ended, element has `final` classname
     */
    afterEnd: (elem: HTMLElement, currentConfig: Config) => void;
  };
  /**
   * You can set what should el-animate do, if new animate function called, but the element is currently animating
   * - `block` means that we should abort new animation calls, while the element is animation
   * - `restart` means that we should stop current animation and start the new one
   * - `replaceToState` means that we only replace final points of animation
   * (el-animate replaces `to` className and animation end handler). **Useful if `animation.type` is `transition`.
   * Then the animation continues without interruption**
   * @default 'restart'
   */
  multiCallHandling: 'block' | 'restart' | 'replaceToState';
}

Also, if in some moment you need to cancel animation and return it to initial point, this is a special function: ElAnimate.cancelAnimation(elem)

Demos

All demos are available here on codepen.io. We highly recommend to view them.

Build

If you want to build this library, then

npm install
npm run build

The result will be in dist/ folder.

Contributing

This project is open for requesting new features, issues, pull requests. It will be constantly maintained especially if there will be activity.