Getting started

Install

npm install @amineyarman/kinesis

import { initKinesis } from "@amineyarman/kinesis"

initKinesis()

Without a build step, this script tag starts Kinesis and exposes window.Kinesis:

<script src="https://cdn.jsdelivr.net/npm/@amineyarman/kinesis/dist/kinesis.global.js"></script>

Importing @amineyarman/kinesis/auto from a CDN also starts it.

Kinesis supports Chrome and Edge 111+, Safari 16.4+, and Firefox 128+. Older browsers get less motion or none.

Mark a scope

data-kinesis marks a scope. Kinesis searches it for animated elements and measures the pointer against it.

<section class="hero" data-kinesis>
  <div class="hero__glow"></div>
  <h1 class="hero__title">Hello</h1>
</section>

Put it on <body> to cover the whole page.

Add a property

.hero__glow {
  --k-parallax: 40px;
}

.hero__title {
  --k-parallax: -12px;
  --k-motion: soft;
}

The glow drifts away from the pointer and the title drifts toward it. Both settle when the pointer leaves.

.layers {
  --k-motion: soft;
  position: relative;
  height: 100%;
  overflow: hidden;
  background: linear-gradient(#bcd4ff, #f1f5ff);
}

.layers > * {
  position: absolute;
}

.layers__sun {
  --k-parallax: -12px;
  top: 40px;
  right: 18%;
  width: 90px;
  height: 90px;
  border-radius: 50%;
  background: #ffcf5a;
}

.layers__far {
  --k-parallax: 18px 6px;
  inset: auto -10% 40px -10%;
  height: 150px;
  border-radius: 50% 50% 0 0 / 100% 100% 0 0;
  background: #8fb0f7;
}

.layers__near {
  --k-parallax: 44px 12px;
  inset: auto -15% -30px -15%;
  height: 130px;
  border-radius: 45% 55% 0 0 / 100% 100% 0 0;
  background: #3d6fe0;
}

.layers__title {
  --k-parallax: -26px -10px;
  inset: 34% 0 auto 0;
  margin: 0;
  text-align: center;
  font-size: 34px;
  letter-spacing: -0.02em;
  color: #0c1324;
}

<div class="layers" data-kinesis>
  <div class="layers__sun"></div>
  <div class="layers__far"></div>
  <div class="layers__near"></div>
  <h3 class="layers__title">Somewhere quiet</h3>
</div>

Add a reaction

--k-when picks a trigger. Outputs set what changes.

.button {
  --k-when: press;
  --k-scale: 0.94;
}

.feature {
  --k-when: view once;
  --k-opacity: 0 1;
  --k-y: 24px 0;
}

The button shrinks while pressed, by mouse, touch, or keyboard. Each feature fades in the first time it scrolls into view. See Reactions.

Frameworks

Vue has a plugin with a v-kinesis directive. React, Svelte, and others use initKinesis() with CSS, or kinesis() in an effect. See Vue and other frameworks.

If nothing moves

• initKinesis() must run in the browser. In server-rendered apps, call it on the client.
• CSS properties only work inside a [data-kinesis] container. kinesis() in JavaScript works anywhere.
• Inline elements can't be transformed. Use display: inline-block or block.
• A transition on the animated properties, usually transition: all, smooths every update twice and makes motion lag. Limit it to other properties.
• With prefers-reduced-motion: reduce, pointer effects stay at rest. See Accessibility.

initKinesis({ debug: true }) reports these problems in the console.