React SlideShow

A lightweight, easy-to-use, and customizable slideshow component for React. Perfect for image galleries, hero banners, or any content rotation needs — with zero external dependencies.

✨ Features

• 🪶 Lightweight - Zero external dependencies, minimal bundle size
• ⚡ Fast & Performant - Built with React best practices
• ♿ Accessible - Screen reader support with ARIA labels
• 🎨 Customizable - Easily style with className prop
• 📱 Responsive - Works great on all screen sizes
• 🔧 TypeScript - Fully typed for better developer experience
• 🎯 Simple API - Easy to integrate and use

🎬 Live Demo

Check out the live demo: https://lyesweb.github.io/react-slideshow/

📦 Installation

npm install react-slideshow-lightweight

or with pnpm:

pnpm add react-slideshow-lightweight

or with yarn:

yarn add react-slideshow-lightweight

🛠 Usage

import SlideShow from 'react-slideshow-lightweight';
import 'react-slideshow-lightweight/dist/style.css';

const images = [
  'https://placehold.co/600x400/png',
  'https://placehold.co/600x400?text=Hello+World',
];

function App() {
  return (
    <div>
      <SlideShow images={images} />
    </div>
  );
}

export default App;

With Custom Starting Index

<SlideShow images={images} defaultIndex={2} />

With Custom Styling

<SlideShow 
  images={images} 
  className="my-custom-slideshow"
/>

📖 API Reference

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | images | string[] | required | Array of image URLs to display | | defaultIndex | number | 0 | Starting slide index | | className | string | '' | Additional CSS class names |

♿ Accessibility Features

• Full ARIA labels and roles
• Screen reader announcements for slide changes
• Focus management
• Visible focus indicators
• Semantic HTML structure

🏗 Architecture

Built with atomic design principles:

• Atoms: Button, Icon
• Molecules: NavigationControls
• Organisms: SlideShow

This modular structure makes the component easy to maintain and extend.

🚀 Development

Clone and Install

git clone https://github.com/LyesWeb/react-slideshow.git
cd react-slideshow
pnpm install

Build the Library

pnpm build

Run Demo App Locally

cd example
pnpm dev

The demo app will be available at http://localhost:5173

Project Structure

react-slideshow/
├── src/
│   ├── components/
│   │   ├── atoms/          # Button, Icon
│   │   ├── molecules/      # NavigationControls
│   │   └── organisms/      # SlideShow
│   ├── index.ts            # Main export
│   └── styles.css          # Tailwind styles
├── example/                # Demo React app
├── dist/                   # Build output
└── package.json

📝 Publishing to npm

1. Update version in package.json
2. Build the library:

   pnpm build

3. Publish to npm:

   npm publish

🗺 Roadmap

Future features planned:

• [ ] Auto-play functionality
• [ ] Slide indicators/dots
• [ ] Keyboard navigation (arrow keys)
• [ ] Touch/swipe gestures
• [ ] Custom transitions
• [ ] Thumbnail navigation
• [ ] Video support
• [ ] Lazy loading

🤝 Contributing

Contributions, issues, and feature requests are welcome!

📄 License

MIT © LyesWeb

See LICENSE for more details.

💖 Support

If you like this project:

• Give it a ⭐️ on GitHub
• Share it with others
• Report bugs or suggest features
• Contribute code via Pull Requests

📊 Stats

Made with ❤️ by LyesWeb