@top-submissions/image-carousel

A lightweight, reusable image carousel component built with vanilla JavaScript. Part of The Odin Project curriculum.

✨ Features

🎯 Pure JavaScript - No dependencies required
⬅️➡️ Navigation arrows - Previous/Next buttons
⚫ Navigation dots - Click to jump to any slide
⏰ Auto-play - Automatically advances every 5 seconds (configurable)
📱 Responsive - Works on all screen sizes
🎨 Customizable - Easy to style and configure
♻️ Reusable - Create multiple carousels on the same page

📦 Installation

Using npm

npm install @top-submissions/image-carousel

Using CDN

<link rel="stylesheet" href="path/to/styles.css">
<script src="path/to/ImageCarousel.js"></script>

🚀 Quick Start

HTML

<!DOCTYPE html>
<html lang="en">
<head>
    <link rel="stylesheet" href="node_modules/@top-submissions/image-carousel/src/css/styles.css">
</head>
<body>
    <div id="my-carousel"></div>
    
    <script src="node_modules/@top-submissions/image-carousel/src/ImageCarousel.js"></script>
    <script src="main.js"></script>
</body>
</html>

JavaScript

// Import if using modules
// const ImageCarousel = require('@top-submissions/image-carousel');

// Define your images
const images = [
    'path/to/image1.jpg',
    'path/to/image2.jpg',
    'path/to/image3.jpg',
    'path/to/image4.jpg'
];

// Initialize the carousel
const carousel = new ImageCarousel(
    document.getElementById('my-carousel'),
    images
);

⚙️ Configuration Options

const carousel = new ImageCarousel(container, images, {
    autoPlayDelay: 5000,    // Time between slides in ms (default: 5000)
    showArrows: true,        // Show prev/next arrows (default: true)
    showDots: true,          // Show navigation dots (default: true)
    autoPlay: true           // Enable auto-play (default: true)
});

Options Details

Option	Type	Default	Description
`autoPlayDelay`	number	5000	Milliseconds between automatic slide transitions
`showArrows`	boolean	true	Display previous/next navigation arrows
`showDots`	boolean	true	Display navigation dots below carousel
`autoPlay`	boolean	true	Automatically advance slides

📚 API Methods

`next()`

Advance to the next slide.

carousel.next();

`previous()`

Go back to the previous slide.

carousel.previous();

`goToSlide(index)`

Jump to a specific slide by index (0-based).

carousel.goToSlide(2); // Go to third slide

`startAutoPlay()`

Start automatic slide transitions.

carousel.startAutoPlay();

`stopAutoPlay()`

Stop automatic slide transitions.

carousel.stopAutoPlay();

`destroy()`

Clean up the carousel and remove all event listeners.

carousel.destroy();

🎨 Customization

The carousel uses CSS classes that you can override:

/* Container */
.carousel-container { }

/* Frame (viewport) */
.carousel-frame { }

/* Slider (moves horizontally) */
.carousel-slider { }

/* Individual slides */
.carousel-slide { }

/* Navigation arrows */
.carousel-arrow { }
.carousel-arrow-prev { }
.carousel-arrow-next { }

/* Navigation dots */
.carousel-dots { }
.carousel-dot { }
.carousel-dot.active { }

💡 Examples

Basic Carousel

const carousel = new ImageCarousel(
    document.getElementById('carousel'),
    ['img1.jpg', 'img2.jpg', 'img3.jpg']
);

Carousel without Auto-Play

const carousel = new ImageCarousel(
    document.getElementById('carousel'),
    images,
    { autoPlay: false }
);

Fast Auto-Play (3 seconds)

const carousel = new ImageCarousel(
    document.getElementById('carousel'),
    images,
    { autoPlayDelay: 3000 }
);

Manual Control Only

const carousel = new ImageCarousel(
    document.getElementById('carousel'),
    images,
    { 
        autoPlay: false,
        showDots: false 
    }
);

Multiple Carousels

// First carousel
const carousel1 = new ImageCarousel(
    document.getElementById('carousel1'),
    ['set1-img1.jpg', 'set1-img2.jpg']
);

// Second carousel
const carousel2 = new ImageCarousel(
    document.getElementById('carousel2'),
    ['set2-img1.jpg', 'set2-img2.jpg']
);

🛠️ Development

Prerequisites

Node.js (v14.0.0 or higher)
npm (v6.0.0 or higher)

Setup

# Clone the repository
git clone https://github.com/top-submissions/fullstackjs-npmpackage-image-carousel.git

# Navigate to directory
cd fullstackjs-npmpackage-image-carousel

# Install dependencies
npm install

Scripts

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Check formatting
npm run format:check

📤 Publishing to npm

First Time Setup

Create npm account (if you don't have one):
```
npm adduser
```
Login to npm:
```
npm login
```
Verify you're part of the @top-submissions organization on npmjs.com

Publishing Steps

Update version in package.json:
```
{
  "version": "1.0.1"
}
```

Commit changes:

git add .
git commit -m "Release v1.0.1"
git tag v1.0.1
git push origin main --tags

Publish to npm:
```
npm publish --access public
```
Note: The --access public flag is required for scoped packages to be public.

Version Updates

Follow semantic versioning:

Patch (1.0.x): Bug fixes
Minor (1.x.0): New features (backward compatible)
Major (x.0.0): Breaking changes

🌐 Browser Support

Chrome (latest 2 versions)
Firefox (latest 2 versions)
Safari (latest 2 versions)
Edge (latest 2 versions)

📄 License

ISC License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

🐛 Issues

Found a bug? Please report it on the GitHub Issues page.

🙏 Acknowledgments

Built as part of The Odin Project curriculum
Project: Dynamic User Interface Interactions - Image Carousel

📞 Contact

GitHub: @top-submissions
Project Link: https://github.com/top-submissions/fullstackjs-npmpackage-image-carousel

Made with ❤️ as part of The Odin Project

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
src		src
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
LICENSE		LICENSE
README.md		README.md
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json

License

top-submissions/fullstackjs-npmpackage-image-carousel

Folders and files

Latest commit

History

Repository files navigation

@top-submissions/image-carousel

✨ Features

📦 Installation

Using npm

Using CDN

🚀 Quick Start

HTML

JavaScript

⚙️ Configuration Options

Options Details

📚 API Methods

next()

previous()

goToSlide(index)

startAutoPlay()

stopAutoPlay()

destroy()