react-kenburns-view

About

Ken Burns effect—slow zoom and pan over still images—for React web applications. Drop in a component, pass an image URL and size, and get smooth motion for heroes, galleries, or slideshows.

Lightweight: No animation library. Uses CSS transforms and requestAnimationFrame. Each instance uses randomized timing and pan direction so multiple images don’t move in lockstep.

For React Native, see react-native-kenburns-view.

Installation

npm install react-kenburns-view

Peer dependencies: React 17+ and React DOM 17+.

Demo

The interactive demo lives in react-library-demos under react-kenburns-view/. See that folder's README for setup (clone both repos as siblings, then npm install and npm run dev).

Usage

import KenBurnsView from 'react-kenburns-view';

function Hero() {
  return (
    <KenBurnsView
      width={1200}
      height={600}
      src="https://example.com/photo.jpg"
      alt="Hero"
      duration={15000}
      zoomStart={1}
      zoomEnd={1.2}
      panX={0.08}
      panY={0.08}
    />
  );
}

API (props)

Prop	Type	Required	Description
width	number	Yes	Container width (px).
height	number	Yes	Container height (px).
src	string	Yes	Image URL.
alt	string	No	Alt text for the image.
placeholder	string	No	Placeholder image URL (optional).
autoStart	boolean	No	Start animation on mount. Default: true.
duration	number	No	Full cycle duration (ms). Default: 20000.
zoomStart	number	No	Start scale. Default: 1.
zoomEnd	number	No	End scale. Default: 1.3.
panX	number	No	Horizontal pan (fraction of width). Default: 0.1.
panY	number	No	Vertical pan (fraction of height). Default: 0.1.
className	string	No	CSS class for the outer container.
style	object	No	Inline styles for the outer container.
children	node	No	Rendered inside the image layer.

Ref API

You can control the animation via a ref:

const ref = useRef();

// Start (or restart) the animation
ref.current?.start();

// Stop the animation
ref.current?.stop();

// Stop and reset progress to 0
ref.current?.reset();

License

ISC

Feedback

Website: nimila.online
Email: nimilahiran@gmail.com
X/Twitter: @nHiRanZ