animarte

v3.0.0

Published

2 months ago

Making the digital world a little more animated place

0High
0Medium
0Low

lucasmc64

loading animation ui ux motion web no-dependency css keyframes animate animarte loader spinner

Animarte

📽️ Animarte

🎯 Goal

This project is a dependency-free library that aims to provide a set of pre-made animations, avoiding rework and Control+C/Control+V between projects.

Note: Click here to see all animations already available!

🎨 How to use it in my project?

🙌 Classic scripts

The project is also exported using UMD, which means that all variables and classes such as the Animarte class and the animations array are exposed globally, and can be used in any script imported after the library.

Note: You should change X.Y.Z to the library version number according to your needs, this is just an example. It is recommended to always use the latest version.
It is recommended that you pin to the latest stable version of the lib. However, if you always want to use the latest version, you can also use latest instead of a predefined version number. Be careful though, breaking changes may be introduced and your project may need to adapt to the changes.

<!DOCTYPE html>

<html>
  <head>
    <!-- ... -->

    <link
      rel="stylesheet"
      href="https://unpkg.com/[email protected]/animarte.css"
    />
    <script src="https://unpkg.com/[email protected]/animarte.js" defer></script>

    <!-- ... -->
  </head>

  <body>
    <div id="loading-animation"></div>
  </body>
</html>

"use strict";

new Animarte({
  animation: "ellipsis",
  variant: "agitated",
  parentElement: document.getElementById("loading-animation"),
});

📦️ ES6 Modules

The HTML is very similar to the classic scripts version, just change the .js extension to .mjs, which will result in something similar to this:

Note: Please read the previous section to get the details involved in importing CSS and choosing a package version, they are the same here.

<script src="https://unpkg.com/[email protected]/animarte.mjs" defer></script>

import { Animarte } from "animarte";

new Animarte({
  animation: "ellipsis",
  variant: "agitated,
  parentElement: document.getElementById("loading-animation"),
});

⚛️ React

Install the lib using your favorite package manager.

npm install animarte

Since the library was designed primarily to be used with vanilla JS, a helper component needs to be created to encapsulate Animarte's behavior and make it simple to reuse throughout the application.

Note: There is TypeScript support, and even if your project doesn't use the JS superset, it should help VSCode and other editors provide autocomplete/code suggestions.

import { memo, useEffect, useRef } from "react";
import { Animarte, AnimarteProps } from "animarte";

import "animarte/animarte.css";

// Example using Vite, React and TypeScript extraxcted from the Animarte website
export const AnimarteWrapper = memo(
  ({ className="", props }: AnimarteProps) => {
    const ref = useRef<HTMLDivElement>(null);

    useEffect(() => {
      const parentElement = ref.current;

      if (parentElement) {
        new Animarte({
          ...props,
          parentElement: parentElement,
        });
      }

      return () => {
        // Required to avoid animation duplication when React is in Strict Mode
        if (parentElement) {
          parentElement.innerHTML = "";
        }
      };
    }, [props]);

    return <div className={`animarte-wrapper ${className}`} ref={ref} />;
  }, 
  (prevProps, nextProps) => {
    function compareObjects(obj1, obj2) {
      const keys1 = Object.keys(obj1);
      const keys2 = Object.keys(obj2);

      if (keys1.length !== keys2.length) {
        return false;
      }

      for (const key of keys1) {
        if (typeof obj1[key] === "object" && typeof obj2[key] === "object") {
          if (!compareObjects(obj1[key], obj2[key])) {
            return false;
          }

          continue;
        }

        if (obj1[key] !== obj2[key]) {
          return false;
        }
      }

      return true;
    }

    return compareObjects(prevProps, nextProps);
  },
);

💅 Use only CSS

Regardless of whether or not you are using a framework to develop your website, you still have the option of simply importing the styles and manually inserting and controlling the animation. Here is an example:

See the previous steps for how to import the CSS into your project.

<div 
	style="--animarte-size: 4em; --animarte-speed: 2.5s; --animarte-color: #d2d2d8;" 
  class="animarte animarte-ellipsis animarte-ellipsis--one-for-all-2"
>
  <div class="animarte-ellipsis__element"></div>
  <div class="animarte-ellipsis__element"></div>
  <div class="animarte-ellipsis__element"></div>
</div>

In the container, the style attribute has the power to change the variables that modify the style and behavior of the animation.
Still in the container, the class attribute must have 3 classes that must respect the following nomenclature:
- animarte: It has styles common to all animation
- animarte-<ANIMATION>: Has specific styles of the type of animation
- animarte-<ANIMATION>--<VARIANT>: Has animation variant specific styles
Child items must have the class attribute that follows the following naming pattern:
- animarte-<ANIMATION>__element: Identifies the items that are part of the animation composition

The number of child items can vary depending on the animation and its variant. So, to know how many child elements you should manually create, click here, search for the animation you want to implement and look at the children attribute.

In the future, we intend to make this information explicit and more easily accessible on the project website!

Note: Besides the bundled CSS file, a CSS file for each animation is generated in animarte/animations/<animation>/<variant>.css. This is useful when you only want to ship the CSS for a specific animation instead of the full bundle.

🧐 Properties and options

You must pass some properties to Animarte to identify which animation you want to use. Now, the parentElement property has a very impractical default value, so it is highly recommended to define it as well. Here are its specifications:

| Property | Type | Default value | Is required? | Description | | --------------- | ------------- | ---------------------- | ------------ | ------------------------------------------------------------ | | animation | string | - | Yes | Animation name | | variant | string | - | Yes | Animation variant name | | parentElement | HTMLElement | window.document.body | No | Element where the animation will be inserted | | options | object | {} | No | Optional properties to change the look or behavior of the animation |

Don't try to pass an input as parentElement, I'm not handling that... yet ‘-’

If you want to tweak the animation a little bit, you can specify a few things by passing the options property. Here's what you can change:

| Property | Type | Default value | Is required? | Description | | ----------- | --------- | ------------- | ------------ | ------------------------------------- | | color | string | - | No | Color used in the animation | | size | string | - | No | Size of the animation | | speed | string | - | No | Speed of the animation | | show | boolean | true | No | Whether the animation should be shown | | ariaLabel | string | - | No | Accessibility label for the animation |

You can experiment with how these options affect the animation by visiting the project website :)

🤔 How do I run the project on my machine?

The first step is to clone the project, either via terminal or even by downloading the compressed file (.zip). After that, go ahead.

🛠️ Requirements

NodeJS and NPM
(Optional) Python
(Optional) Yarn

🔍️ Installing dependencies

With Node.JS installed, access the project directory via terminal and run the npm install command. If you prefer to use Yarn, just run the yarn command. Now, you will need to install the sass package globally which is responsible for processing the .scss files and generating the .css files.

# Using NPM
npm i -g sass

# Using Yarn
yarn global add sass

Now, if you intend to use live-server to serve CSS, you will also need to install it globally.

If you prefer to use Python for this, you don't need to install anything else.

# Using NPM
npm i -g live-server

# Using Yarn
yarn global add live-server

If you prefer to use Python, you can modify the NPM Script start as follows:

"start": "gulp watchAll & python3 -m http.server 5645"

✨ Running the project

With the dependencies properly installed, still in the terminal, run npm start or yarn start.

If the port has not been manually changed and the default port is free, simply access access the address http://127.0.0.1:5645/demo in your favorite browser, to see the project running.

🎉 If everything went well...

Now you are running the project beautifully!

✏️ License

This project is under the GPL v3 license. See the LICENSE for more information.

Made with 💜 by a dreamer