TypeScript icon, indicating that this package has built-in type declarations

0.3.6 • Public • Published

Css-Var-Animate React

Welcome to my little package, this is a super lightweight library (actually they are just a few React hooks) to animate css variable with js, to achieve animations you couldn't do with CSS alone. Built to be performant by using combination of events, intersection observer, requestAnimationFrame.


Probably easiest to see it in action on the demo page. The demo page is part of the git repo, find the code here and the styles here.


all together - 3.5 kB useCounter - 1.33 kB useScroller - 1.84 kB useMouseover - 1kB

Still figuring out how to optimise the package to be smaller, but the hooks themselves are super short (and simple). Also still working on module exports, to import each hook separately import useScroller from "css-var-animate/scroller";, but it doesn't seem to be working (input welcome), so for now import them all through index : import { useCounter, useMouseover, useScroller } from "css-var-animate";


CSS variables are really powerful, and in future we will be able to animate them aswell (with CSS @property), but since the support is not great for this yet, I built a hook that animates a css variable for you, tweening the value from a start to stop value. This is different from other js libs i saw that run animations, or that animate a text value in your html.

This essentially tweens a value from 0 to 1, and applies this value as a CSS custom property.


start({ ref, id, ms, easing?, bezier? }) The start function takes a config object of

  • ref : a React ref to the object it should apply the CSS properties to
  • id : the name of the custom property
  • ms : the duration of the 'tween'
import { useCounter } from "css-var-animate";

const Component = ()=>{
    const objectRef = useRef();
    const { start } = useCounter();

    // Run on event or action with config object
    const animate = ()=>start({
        ref: objectRef,
        id: "--x",
        ms: 800,
    return (<div>
        <button onClick={animate)>Run</button>
        <div ref={objectRef}></div>

You can optionally add one of the default easing functions ("linear" by default) : easing: "linear" | "ease-in" | "ease-out" | "ease-in-out" or points for a custom bezier easing function : bezier: [1, 0, 0, 1],


Sites are dynamic now and it should be easy to animate on scroll. This function takes a useRef to an element and updates a css variable with it's relative scroll position. This can then be used in CSS to animate with or on scroll.


This hook takes a config object. All it needs to run the standard behaviour is the ref to the element it should apply the css variables to.

import { useScroller } from "css-var-animate";
const Component = ()=>{
    const scrollRef = useRef();
    useScroller({ ref: scrollRef });

    return (<div ref={scrollRef} >...</div>)

by default it will apply --s the distance scrolled since it came into view, and --v a relative measure from 0 to 1, from the moment it first enters, to the moment it last leaves the view. Best see this in action in the demo.

You can customise the variables names and values by passing your own callback function. The callback function receives

    ref: allRef,
    customVars: ({ view, scroll, top, bottom }) => ({
        "--s": scroll,
        "--v": view,
        "--t": top,
        "--b": bottom


For effects on mouse-move use this simple hook to get a 0 to 1 index in where the mouse cursor is relative to the element --mx and --my.


Just as easy as the others, this hook also just needs the ref to the element it should add the event listener to, and apply the css custom properties to.

import { useMouseover } from "css-var-animate";
const Component = ()=>{
    const mouseRef = useRef();

    return (<div ref={mouseRef} >...</div>)


Of course dependend on React & typescript, only 1 dependency is npm package : bezier-easing used for useCounter tweening. and rollup for building


We all love js animation libraries but they do increase our code size. This is for when you don't want to go full gsap just for a few simple animations. Minimal js that simply animates CSS variables (AKA custom properties), for you to do the rest in CSS.


Credit where it's due. I have been enlightened to the use of CSS variables by Lea Verou. See her great course on Frontend Masters, or the shorter version on Youtube : CSS Variable Secrets and read her articles on custom properties with defaults. She did an example CSS animation copying the Material UI button effect using @property, and I thought this could be widely supported by using some minimal js to animate the variable.

Package Sidebar


npm i css-var-animate

Weekly Downloads






Unpacked Size

42.5 kB

Total Files


Last publish


  • britnell