Simple image slider component with left to right slide animation.
npm install imageslider-nextA small, framework-agnostic image slider component built with Tailwind CSS and TypeScript. This package now supports passing a custom image component (for example, Next.js Image) so you can enable optimized images inside Next.js projects.
``zsh`
npm i imageslider-nextor
pnpm add imageslider-next
- Lightweight, accessible image slider.
- Accepts a custom ImageComponent (e.g. next/image) for optimized images.imageProps
- forwarding for responsive behavior (e.g. sizes, priority, objectFit).
- Responsive native fallback when no ImageComponent is provided.
- Fixed: each slider instance is independent; controls no longer collide across multiple instances.
`tsx
import ImageSliderNext from 'imageslider-next';
const data = [
{ id: 1, imageUrl: '/images/1.jpg', title: 'One', alt: 'One', width: 1200, height: 800 },
{ id: 2, imageUrl: '/images/2.jpg', title: 'Two', alt: 'Two', width: 1200, height: 800 },
{ id: 3, imageUrl: '/images/3.jpg', title: 'Three', alt: 'Three', width: 1200, height: 800 },
];
sliderClassName="w-full shadow-md h-64 sm:h-80 rounded-lg"
slideClassName=""
buttonClassName="w-3 h-3 rounded-full bg-black/50"
imageWidth={1200}
imageHeight={800}
/>
`
for optimizationIf you use Next.js, pass Image as the ImageComponent prop and optionally forward imageProps to enable responsive loading. Example:
`tsx
import Image from 'next/image';
import ImageSliderNext from 'imageslider-next';
import img1 from '@/public/1.jpg';
const slides = [
{ id: 1, imageSrc: img1, title: 'First', alt: 'first', width: 1200, height: 800 },
// ...
];
sliderClassName="w-full shadow-md h-[50vh] rounded-lg"
ImageComponent={Image}
imageProps={{ sizes: '100vw', priority: true }}
imageWidth={1200}
imageHeight={800}
/>
`
Notes:
- We intentionally strip fill: true when forwarded to avoid layout issues inside the slider (the slider manages layout). If you need fill behavior, you can implement a wrapper with an explicit aspect ratio on your slide.width
- Provide /height per item or use imageWidth/imageHeight defaults to help the component calculate correct sizes.
To run the component locally with Storybook:
`bash`
npm run storybookor
pnpm storybook
There are example stories that show a native fallback and usage with a mock Image component. Use the With Image Component story to test integration.
Hosted Storybook: https://imageslider-next.vercel.app/
If your TypeScript setup complains about importing image files, add a simple declaration file src/types/images.d.ts:
`ts`
declare module '*.jpg';
declare module '*.png';
declare module '*.svg';
declare module '*.webp';
declare module '*.avif';
Also, for local development you may want to add React type declarations if you see missing types:
`bash`
npm install -D @types/react @types/react-dom
ImageSliderNext props (high level):
- data: ItemData[] — items to render. Each item supports imageUrl, imageSrc (imported images), title, alt, width, height.sliderClassName: string
- — classes applied to slider root.slideClassName: string
- — classes applied to each slide.buttonClassName: string
- — classes applied to pagination buttons.imageWidth?: number
- , imageHeight?: number — defaults used when per-item sizes missing.ImageComponent?: React.ComponentType
- — optional image component (pass Next's Image).imageProps?: Record
- — forwarded props for the image component (we strip fill).
PRs welcome — please run npm run build and npm run storybook` to test changes locally.