@aminerman/kinesis v1.4.26

Kinesis.js

Author: Amine Bouyarmane
License: MIT

Kinesis.js is a lightweight, TypeScript-powered library that enables you to create complex and interactive animations with ease. Whether you're looking to add depth effects, audio-reactive elements, scroll-based transformations, or path-following animations, Kinesis.js has you covered.

Installation

You can install Kinesis.js via npm or yarn:

npm install @aminerman/kinesis

or

yarn add @aminerman/kinesis

Getting Started

To start using Kinesis.js in your project, initialize it by importing and calling the initializeKinesis function. This function scans your DOM for elements with specific data-ks-* attributes and initializes the corresponding Kinesis components.

import { initializeKinesis } from "@aminerman/kinesis";

document.addEventListener("DOMContentLoaded", () => {
  initializeKinesis();
});

Components

Kinesis.js provides several components to create various interactive animations. Each component targets elements with specific data-ks-* attributes and applies transformations based on user interactions or other triggers.

KinesisTransformer

Description: Applies transformations (translate, rotate, scale, tilt) to elements based on mouse movement or scroll interaction. Usage:

<div class="container" data-kinesistransformer data-ks-interaction="mouse">
  <div
    class="transform-element"
    data-kinesistransformer-element
    data-ks-strength="30"
    data-ks-transform="rotate"
    data-ks-axis="Z"
  ></div>
  <!-- More transform elements -->
</div>

KinesisDepth

Description: Creates a parallax depth effect by translating elements along the Z-axis. Then container moves by rotating around the X and Y axis, showcasing the depth effect. Usage:

<div class="container" data-kinesisdepth data-ks-sensitivity="10">
  <div
    class="depth-element"
    data-kinesisdepth-element
    data-ks-depth="-20"
  ></div>
  <!-- More depth elements -->
</div>

KinesisAudio

Description: Applies audio-reactive transformations to elements based on audio frequency data. Usage:

<div
  class="container"
  id="audio"
  data-kinesisaudio
  data-ks-audio="audio.mp3"
  data-ks-playaudio="false"
>
  <div
    class="audio-element"
    data-kinesisaudio-element
    data-ks-audioindex="60"
    data-ks-strength="50"
    data-ks-type="scale"
  ></div>
  <!-- More audio elements -->
  <button id="play-audio">Play Audio</button>
  <button id="stop-audio">Stop Audio</button>
</div>

<script>
  window.addEventListener("DOMContentLoaded", () => {
    const playButton = document.getElementById("play-audio");
    const stopButton = document.getElementById("stop-audio");
    const container = document.getElementById("audio");
    const kinesisAudio = container._kinesisAudio;

    if (playButton && kinesisAudio) {
      playButton.addEventListener("click", () => kinesisAudio.play());
    }

    if (stopButton && kinesisAudio) {
      stopButton.addEventListener("click", () => kinesisAudio.stop());
    }
  });
</script>

KinesisScrollItem

Description: Applies transformations to the element based on scroll. This is a standalone component. It doesn't need to be inside KinesisTransformer. Usage:

<div class="scroll-item-container container">
  <div
    class="scroll-item"
    data-kinesisscroll-item
    data-ks-transform="scale"
    data-ks-axis="X, Y"
    data-ks-strength="100"
    style="background-color: lightgreen; width: 50px; height: 50px"
  ></div>
</div>

KinesisPath

Description: Moves elements along a predefined SVG path based on mouse movement or scroll interaction. Usage:

<div
  class="path-container"
  data-kinesispath
  data-ks-path="M 100,300 C 200,100 400,500 500,300"
  data-ks-duration="100"
  data-ks-interaction="scroll"
>
  <!-- Path Elements -->
  <div
    class="path-element"
    data-kinesispath-element
    data-ks-strength="1"
    data-ks-offset="0"
  ></div>
  <div
    class="path-element"
    data-kinesispath-element
    data-ks-strength="0.5"
    data-ks-offset="50"
  ></div>
</div>

KinesisDistanceItem

Description: Transforms elements based on the distance between the mouse pointer and the element. Usage:

<div class="distance-container">
  <div
    class="distance-item"
    data-kinesisdistance-item
    data-ks-transform="rotate"
    data-ks-axis="X, Y"
    data-ks-strength="20"
    data-ks-velocity="deceleration"
  ></div>
  <!-- More distance items -->
</div>

Attributes

KinesisAudio Attributes

Note: Container for KinesisAudioElement

KinesisAudioElement Attributes

Note: Child of KinesisAudio container.

KinesisDepth Attributes

Note: Container for KinesisDepthElement

KinesisDepthElement Attributes

Note: Child of KinesisDepth container.

KinesisDistanceItem Attributes

Note: Standalone component

KinesisPath Attributes

Note: Container for KinesisPathElement

KinesisPathElement Attributes

Note: Child of KinesisPathElement

KinesisScrollItem Attributes

Note: Standalone component

KinesisTransformer Attributes

Note: Container for KinesisTransformerElement

KinesisTransformerElement Attributes

Note: Child of KinesisTransformer

Usage Examples

Below are several examples demonstrating how to use Kinesis.js components in your projects.

Simple Depth Effect

Description: Creates a parallax depth effect with multiple layers that move based on mouse interactions.HTML:

<div class="container" data-kinesisdepth data-ks-sensitivity="10">
  <div
    class="depth-element"
    data-kinesisdepth-element
    data-ks-depth="-20"
  ></div>
  <div
    class="depth-element"
    data-kinesisdepth-element
    data-ks-depth="-40"
  ></div>
  <div
    class="depth-element"
    data-kinesisdepth-element
    data-ks-depth="-60"
  ></div>
</div>

Translate on Scroll on X and Y Axes

Description: Applies rotation transformations to elements as the user scrolls, creating a dynamic visual effect.HTML:

<div class="container" data-kinesistransformer data-ks-interaction="scroll">
  <div
    class="transform-element"
    data-kinesistransformer-element
    data-ks-strength="30"
    data-ks-transform="rotate"
    data-ks-axis="Z"
  ></div>
  <div
    class="transform-element"
    data-kinesistransformer-element
    data-ks-strength="-60"
    data-ks-transform="rotate"
    data-ks-axis="Z"
  ></div>
  <div
    class="transform-element"
    data-kinesistransformer-element
    data-ks-strength="90"
    data-ks-transform="rotate"
    data-ks-axis="Z"
  ></div>
</div>

Standalone Scroll Item

Description: Transforms a single element based on its visibility within the viewport during scrolling.HTML:

<div class="scroll-item-container container">
  <div
    class="scroll-item"
    data-kinesisscroll-item
    data-ks-transform="scale"
    data-ks-axis="X, Y"
    data-ks-strength="100"
    style="background-color: lightgreen; width: 50px; height: 50px"
  ></div>
</div>

Path-Following Elements

Description: Moves elements along a predefined SVG path based on scroll interaction.HTML:

<div
  class="path-container"
  data-kinesispath
  data-ks-path="M 100,300 C 200,100 400,500 500,300"
  data-ks-duration="100"
  data-ks-interaction="scroll"
>
  <!-- Path Elements -->
  <div
    class="path-element"
    data-kinesispath-element
    data-ks-strength="1"
    data-ks-offset="0"
  ></div>
  <div
    class="path-element"
    data-kinesispath-element
    data-ks-strength="0.5"
    data-ks-offset="50"
    style="background-color: lightblue"
  ></div>
</div>

Simple Audio Effect

Description: Applies scaling transformations to elements based on audio frequency data. Controls to play and stop the audio are provided.HTML:

<div
  class="container"
  id="audio"
  data-kinesisaudio
  data-ks-audio="audio.mp3"
  data-ks-playaudio="false"
>
  <div
    class="audio-element"
    data-kinesisaudio-element
    data-ks-audioindex="60"
    data-ks-strength="50"
    data-ks-type="scale"
  ></div>
  <div
    class="audio-element"
    data-kinesisaudio-element
    data-ks-audioindex="80"
    data-ks-strength="50"
    data-ks-type="scale"
  ></div>
  <div
    class="audio-element"
    data-kinesisaudio-element
    data-ks-audioindex="100"
    data-ks-strength="50"
    data-ks-type="scale"
  ></div>
</div>
<div class="control-buttons">
  <button id="play-audio">Play Audio</button>
  <button id="stop-audio">Stop Audio</button>
</div>

<script>
  window.addEventListener("DOMContentLoaded", () => {
    const playButton = document.getElementById("play-audio");
    const stopButton = document.getElementById("stop-audio");
    const container = document.getElementById("audio");
    const kinesisAudio = container._kinesisAudio;

    if (playButton && kinesisAudio) {
      playButton.addEventListener("click", () => kinesisAudio.play());
    }

    if (stopButton && kinesisAudio) {
      stopButton.addEventListener("click", () => kinesisAudio.stop());
    }
  });
</script>

Tilt Effect

Description: Applies a tilt transformation to elements based on mouse interactions.HTML:

<div data-kinesistransformer class="tilt-container">
  <div data-kinesistransformer-element data-ks-transform="tilt">Hello</div>
  <div data-kinesistransformer-element data-ks-transform="tilt">Hello</div>
  <div
    data-kinesistransformer-element
    data-ks-transform="tilt"
    data-ks-strength="50"
  >
    Hello
  </div>
</div>

License

Kinesis.js is licensed under the MIT License .