# vue-kinesis splits into a container that listens and elements that move

> vue-kinesis is a set of Vue components that turn pointer movement or scroll position into transforms on child elements, with motion type, strength, axis and range exposed as props. Its own README now points new projects at a successor, Kinesis 2.0, written as CSS custom properties instead of a Vue plugin.

**amineyarman/vue-kinesis** — Easily create complex interactive animations with Vue.js

- Repository: https://github.com/amineyarman/vue-kinesis
- Website: https://www.aminerman.com/kinesis/
- Stars: 1,498 · Forks: 57
- Language: JavaScript
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/amineyarman-vue-kinesis

## The container listens, the element moves

The API is split across two components and that split is the design. `kinesis-container` is the listener, `kinesis-element` is the thing that moves. The container decides what input drives the animation and how the space is measured; each element decides how it responds.

On the container, `event` chooses the trigger and takes `move` or `scroll`, defaulting to `move`. `duration` sets the parallax speed in milliseconds with a default of 1000, and `easing` defaults to the CSS value `cubic-bezier(0.23, 1, 0.32, 1)`. `active` switches interaction off entirely without unmounting the tree, and `tag` lets the container render as any valid HTML tag instead of a `div`.

The perspective prop defaults to 1000 and is documented as effective for the `depth` parallax type, which is the 3D case. Two props attach sound: `audio` takes a path to an audio file and `playAudio` starts and stops it.

The element carries the motion parameters. `strength` defaults to 10 and scales the effect, `type` picks what transform is applied, and `cycle` sets how many times the movement repeats, with 0 as the default.

You can nest elements inside one container and they will react independently, which is how you get a layered parallax without any JavaScript of your own.

## type chooses the transform, originX and originY choose the pivot

The `type` prop on `kinesis-element` accepts seven values, and the default is `translate`: translate, rotate, scale, scaleX, scaleY, depth, and depth_inv. The last two are the interesting pair, since the inverse variant exists specifically for the cases where depth moves the wrong way for your scene.

Because these are CSS transform names rather than bespoke animation types, the library composes with existing transform styles better than you might expect. `transformOrigin` is documented as similar to the CSS transform-origin property and defaults to `center`.

The two origin props are the part that takes a moment to read. `originX` and `originY` are numbers on a scale where 50 is the centre of the container, 0 the left or top edge and 100 the right or bottom edge. They describe where in the container the motion pivots, which is different from where the element sits. Change `originY` to 0 and an element tracks the pointer relative to the top of the container instead of its middle, which changes the feel of a card stack without changing `strength`.

All of this is expressed as attributes in your template, so nothing needs to be read from JavaScript state. The values are static per component, and the motion itself is computed from pointer or scroll position.

## Axis and range props are what keep motion usable

Unconstrained parallax is where interactive animation libraries earn their reputation for feeling cheap, and the range props here are the answer.

`axis` constrains movement to a single axis and accepts `x` or `y`, with `null` as the default meaning no constraint. Then four numeric props bound the travel: `maxX`, `minX`, `maxY` and `minY`, all defaulting to `null`. A horizontal-only banner with a fixed travel distance is a matter of setting the axis and clamping one dimension.

`cycle` controls repetition, defaulting to 0.

What the props table does not document is worth stating, because it is the gap you will hit. There is no documented prop for respecting a reduced motion preference, no prop for disabling motion on small screens, and no mention anywhere of keyboard or screen reader behaviour. If your project has an accessibility policy, nothing here helps you meet it automatically. You would pair the components with your own media query or user preference check and set `active` to false.

The browser story is the other gap. The README shows a plain script tag usage for Vue 2, and nothing states what happens when the page is scrolled rather than moved, which is the `scroll` event value, nor how the audio props behave on a browser that blocks autoplay until user interaction.

## Two install tags for two Vue majors

There are two lines of the library published under one package name, and picking the wrong one is the most common setup mistake.

For Vue 3 the README gives the next tag:

```sh
npm install --save vue-kinesis@next
```

Then register the plugin when creating the app:

```javascript
import { createApp } from "vue";
import App from "./App.vue";
import VueKinesis from "vue-kinesis";

const app = createApp(App);
app.use(VueKinesis);

app.mount("#app");
```

For Vue 2 the untagged install is the one you want:

```sh
npm install --save vue-kinesis
```

```javascript
import Vue from 'vue'
import VueKinesis from 'vue-kinesis'

Vue.use(VueKinesis)
```

You do not have to take every component. Named imports let you register only what a page uses, which matters for a site with a mostly static bundle:

```javascript
import Vue from 'vue'
import { KinesisContainer, KinesisElement } from 'vue-kinesis'

Vue.component('kinesis-container', KinesisContainer)
Vue.component('kinesis-element', KinesisElement)
```

There is also a browser build for pages without a bundler, which loads Vue and the library as two scripts:

```html
<script src="vue.js"></script>
<script src="vue-kinesis.min.js"></script>
```

Note that no Vue 3 equivalent of that script tag path is shown in the README, so a no-build Vue 3 setup is not a documented case.

The usage guide itself lives outside the repository, on the author's demo site, which is linked as How to use rather than reproduced in the README.

## Four bundles built by Rollup, with zero runtime dependencies

The package.json tells you more about the project than the prose does.

There are no runtime dependencies at all, the dependencies object is empty. Everything ships in dist, and the build scripts produce four targets from one Rollup config in build/rollup.config.js: an SSR format, an ES module format, a CommonJS format for SSR, and an IIFE build for unpkg. Each sets NODE_ENV to production through cross-env.

The entry points map onto those formats. `main` points at `dist/vue-kinesis.ssr.js`, `module` and `browser` both point at `dist/vue-kinesis.esm.js`, and `unpkg` points at `dist/vue-kinesis.min.js`. A separate `serve` script runs the Vue CLI service against `dev/serve.js` for local development of the components themselves, and `lint` runs the Vue CLI linter.

A dedicated SSR build existing at all is worth noting, since interactive animation libraries often break when the markup is rendered on a server. It is also why the version in package.json reads 1.3.3 while the Vue 3 release is numbered v2.0.5: the two lines share a repository but not a version counter.

The toolchain is dated. Vue CLI 4.5, Rollup 2, Babel 7, ESLint 6 and eslint-plugin-vue 6 are the pinned dev dependencies, and the peer dependency is declared as Vue `^2.6.11`. That peer range describes the Vue 2 line, so the Vue 3 build is not what the metadata describes.

## The maintainer redirects new projects to Kinesis 2.0

The first thing in the README is a notice, and it changes how you should read everything below it.

Kinesis 2.0 lives at kinesisjs.com, is installed with `npm i @amineyarman/kinesis`, and expresses the same idea as CSS custom properties rather than as components. The example in the notice sets a tilt on a card by declaring `--k-tilt: 8deg`. It also ships a Vue plugin named `v-kinesis`.

The difference in approach is the point. The old library moves elements by computing transforms in JavaScript and applying them through Vue reactivity. The new one expresses the same behaviour as CSS variables on the element, which means no framework is required, and the Vue integration becomes one plugin rather than a component tree.

The README says vue-kinesis stays available for existing projects. That framing matters for your decision: this is a maintained successor, not an abandoned branch, so choosing vue-kinesis for new work means choosing the older mechanism on purpose.

There is also a documented migration path from a predecessor, vue-mouse-parallax. Components map by name, `parallax-container` becomes `kinesis-container` and `parallax-element` becomes `kinesis-element`. Props are renamed rather than reworked: `parallaxStrength` becomes `strength` and `animationDuration` becomes `duration`. Two prop values change with them, `translation` becoming `translate` and `rotation` becoming `rotate`.

The licence is MIT.

## Conclusion

Adopt vue-kinesis for an existing Vue 2 or Vue 3 project that already depends on pointer-driven motion and wants declarative ranges and axis constraints; skip it for new work, because the maintainer directs new projects to the CSS-property rewrite `@amineyarman/kinesis` instead. Verify first that your Vue major matches the tag you install, since the Vue 3 build sits behind the `next` tag while `vue-kinesis` without a tag resolves to the Vue 2 build.

## FAQ

### How do I install vue-kinesis for Vue 3?

Install the next tag with `npm install --save vue-kinesis@next`, then import VueKinesis and register it with `app.use(VueKinesis)` after `createApp`. The untagged install is the Vue 2 line.

### What is the difference between vue-kinesis and Kinesis 2.0?

Kinesis 2.0 is the same idea rewritten as CSS custom properties such as `--k-tilt`, needs no framework, and ships its own Vue plugin `v-kinesis`. It is installed as `@amineyarman/kinesis`, while vue-kinesis remains available for existing projects.

### Can I limit an element's movement to one axis?

Yes. The `axis` prop takes `x` or `y` to constrain movement, and `maxX`, `minX`, `maxY` and `minY` bound the range on each axis, all defaulting to `null` for no limit.

## Sources

- [amineyarman/vue-kinesis on GitHub](https://github.com/amineyarman/vue-kinesis)
- [License: MIT](https://github.com/amineyarman/vue-kinesis/blob/master/LICENSE)
- [Project website](https://www.aminerman.com/kinesis/)
- [README](https://github.com/amineyarman/vue-kinesis/blob/master/README.md)
- [Releases](https://github.com/amineyarman/vue-kinesis/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/amineyarman-vue-kinesis