fill-slider-animation

A reusable clip-path fill-overlay slider for React. The next slide animates over the current one (right-to-left or left-to-right) instead of fading or swapping. Ideal for landing pages, hero sections, and project showcases.

Installation

npm install fill-slider-animation
# or
yarn add fill-slider-animation
# or (from local packages folder)
npm install ../packages/fill-slider-animation

Quick Start

import { useFillSlider, FillSlider } from "fill-slider-animation";
import "fill-slider-animation/styles.css";

const slides = [
  { src: "/img1.jpg", title: "Slide 1" },
  { src: "/img2.jpg", title: "Slide 2" },
];

// Option 1: Use the hook (full control)
function MySlider() {
  const { activeIndex, overlay, goNext, goPrev, displayIndex } = useFillSlider({
    itemCount: slides.length,
    duration: 2400, // ms, must match CSS
  });

  return (
    <div className="relative w-full h-screen">
      {/* Base layer */}
      <div className="absolute inset-0">
        <img src={slides[activeIndex].src} alt="" className="w-full h-full object-cover" />
      </div>

      {/* Overlay (during transition) */}
      {overlay && (
        <div className={`fill-slider-overlay fill-slider-overlay--${overlay.direction}`}>
          <img src={slides[overlay.index].src} alt="" className="w-full h-full object-cover" />
        </div>
      )}

      <button onClick={goPrev}>Prev</button>
      <button onClick={goNext}>Next</button>
      <h2>{slides[displayIndex].title}</h2>
    </div>
  );
}

// Option 2: Use the component (render props)
function MySliderWithComponent() {
  return (
    <FillSlider
      items={slides}
      renderSlide={(item) => (
        <img src={item.src} alt={item.title} className="w-full h-full object-cover" />
      )}
      duration={2400}
    >
      {({ layers, goNext, goPrev, displayItem }) => (
        <div className="relative w-full h-screen">
          <div className="absolute inset-0">{layers}</div>
          <button onClick={goPrev}>Prev</button>
          <button onClick={goNext}>Next</button>
          <h2>{displayItem.title}</h2>
        </div>
      )}
    </FillSlider>
  );
}

API

useFillSlider(options)

| Option | Type | Default | Description | |--------------|----------|---------|--------------------------------------| | itemCount | number | — | Total number of slides | | duration | number | 2400 | Animation duration in ms | | loop | boolean | true | Loop at end (prev/next wrap around) |

Returns:
{ activeIndex, overlay, displayIndex, goNext, goPrev, isTransitioning }

• activeIndex — Current slide index
• overlay — { index, direction } or null during transition
• displayIndex — Use for title/description (overlay during transition, else active)
• goNext / goPrev — Navigation handlers
• isTransitioning — true while animation runs

FillSlider component

| Prop | Type | Default | Description | |-----------------|----------|---------|-------------------------------------------| | items | T[] | — | Array of slide data | | renderSlide | function | — | (item, index, { isOverlay }) => ReactNode| | duration | number | 2400 | Animation duration in ms | | loop | boolean | true | Loop at end | | layerClassName| string | — | Class for base/overlay inner wrappers | | renderThumb | function | — | Optional thumbnail (item, index) => ReactNode | | thumbTrackClassName | string | — | Class for thumb track | | children | function | — | Render prop ({ layers, thumb, goNext, goPrev, displayItem, ... }) => ReactNode |

CSS classes

• fill-slider-overlay — Overlay container (position absolute, inset 0)
• fill-slider-overlay--next — Direction: right → left
• fill-slider-overlay--prev — Direction: left → right
• fill-slider-thumb-track — Thumbnail container
• fill-slider-thumb-base — Thumb base layer
• fill-slider-thumb-overlay / --next / --prev — Thumb overlay

CSS variables

:root {
  --fill-slider-duration: 2.4s;
  --fill-slider-easing: cubic-bezier(0.34, 1.35, 0.64, 1);
}

Override on .fill-slider-overlay or a parent to change animation timing.

How it works

The overlay is clipped with clip-path: inset(). The visible region is animated:

• Next: inset(0 0 0 100%) → inset(0 0 0 0) — reveal from right
• Prev: inset(0 100% 0 0) → inset(0 0 0 0) — reveal from left

No transform-based sliding; pure clip-path for smooth, GPU-friendly animation.

Using in other projects

Option A: Copy the package

Copy the packages/fill-slider-animation folder into your project (e.g. lib/fill-slider-animation), then:

npm install
# In your package.json:
"fill-slider-animation": "file:./lib/fill-slider-animation"

Option B: Publish to npm

cd packages/fill-slider-animation
npm login                    # If not logged in
npm run build                # Ensure dist is up to date
npm publish                 # Unscoped
# Or for scoped (if name is taken): npm publish --access public

# Then in any project:
npm install fill-slider-animation

Option C: Monorepo / workspace

Add to your root package.json:

{
  "workspaces": ["packages/*"],
  "dependencies": {
    "fill-slider-animation": "workspace:*"
  }
}

License

MIT