Custom Image Carousel

A lightweight, easy-to-use image carousel component with navigation dots, arrow controls, and smooth scrolling. Perfect for showcasing images in a clean, responsive interface.

Live Demo - See the component in action!

Features

• 🖼️ Smooth Image Scrolling - Seamless transition between images using CSS scroll snapping
• 🔢 Navigation Dots - Visual indicators showing current position in the carousel
• ⬅️ Arrow Controls - Intuitive navigation buttons that appear/disappear intelligently
• 📱 Responsive Design - Automatically adapts to different screen sizes
• 🔄 Smart Navigation - Arrows hide at the beginning/end of carousel for better UX
• 🚫 Controlled Scrolling - Prevents accidental user scrolling for more predictable behavior
• ✨ Easy Integration - Simple API with minimal configuration required
• 🪶 Lightweight - No external dependencies except for minimal CSS
• 🎯 Targeted Design - Clean interface focused on showcasing your images
• 🔄 Auto Cycling - Built-in support for automatic image cycling
• 🔗 Image Linking - Add clickable links to your carousel images

Installation

First, install the package in your project:

npm install @pd200x/custom-image-carousel

Manual Installation (Without npm)

If you're not using npm, you can manually download and include these two essential files:

1. custom-image-carousel.js - The main component JavaScript file
2. component.css - The required CSS styles

You can find these files:

• From the GitHub repo:
  • src/js/components/custom-image-carousel.js
  • src/css/component.css

Then include them in your HTML:

<link rel="stylesheet" href="path/to/component.css" />
<script src="path/to/custom-image-carousel.js"></script>

Getting Started (Beginner-Friendly Guide)

Step 1: Add a container element in your HTML

<div id="my-carousel" style="height: 400px;"></div>

Step 2: Import and use the component in your JavaScript

// Import the component
import { CustomImageCarousel, ImageItem } from "@pd200x/custom-image-carousel";

// Create an array of image items
const imageItems = [
  new ImageItem({ src: "path/to/image1.jpg" }),
  new ImageItem({
    src: "path/to/image2.jpg",
    link: "https://example.com",
    mode: "_blank",
  }),
  new ImageItem({ src: "path/to/image3.jpg", link: "https://anothersite.com" }),
];

// Create and initialize the carousel
const carousel = new CustomImageCarousel({
  containerID: "my-carousel", // ID of your container from Step 1
  imageItemArray: imageItems, // Image items from above
});

// IMPORTANT: Always call initialise() to set up the carousel
carousel.initialise();

That's it! Your image carousel is ready to use.

How to Customize the Look

You can easily change how the carousel looks by targeting these CSS classes:

Main Classes You Can Style

• .mcic-container - The entire carousel container
• .mcic-image-group - The scrollable area containing images
• .mcic-image-container - Individual image containers
• .mcic-navigation-dots-container - Container for navigation dots
• .mcic-navigation-dot - Individual navigation dots
• .mcic-navigation-dot-selected - The currently selected dot
• .mcic-left-arrow-button - Left navigation arrow
• .mcic-right-arrow-button - Right navigation arrow

Example: Custom Styling

/* Make the carousel container more stylish */
.mcic-container {
  border-radius: 12px !important;
  box-shadow: 0 10px 30px rgba(0, 0, 0, 0.15) !important;
}

/* Style the navigation dots */
.mcic-navigation-dot {
  height: 12px !important;
  width: 12px !important;
  background-color: #e0e0e0 !important;
}

/* Style the selected dot */
.mcic-navigation-dot-selected {
  background-color: #4a5568 !important;
  transform: scale(1.2) !important;
}

/* Style the navigation arrows */
.mcic-left-arrow-button,
.mcic-right-arrow-button {
  background-color: rgba(255, 255, 255, 0.8) !important;
  border-radius: 50% !important;
  padding: 10px !important;
}

Important Note about Styling

You may need to use !important in your CSS rules when customizing the component styles if your own CSS specificity is not high enough to override the component's built-in styles.

Don't Forget to Initialize Your Carousel!

The Critical Step: initialise()

After creating your carousel, you must call the initialise() method to make it work:

// Create your carousel
const carousel = new CustomImageCarousel({
  // ...your options here
});

// ALWAYS do this or your carousel won't work!
carousel.initialise();

This step is essential because it:

• Creates the DOM structure for the carousel
• Sets up event listeners for controls
• Initializes the navigation system

API Reference

CustomImageCarousel Options

| Option | Type | Required | Description | | ---------------- | ----------- | -------- | ----------------------------------------------------- | | containerID | string | Yes | ID of the HTML element that will contain the carousel | | imageItemArray | ImageItem[] | Yes | Array of images to display in the carousel |

ImageItem Options

| Option | Type | Required | Description | | ------ | ------ | -------- | -------------------------------------------------------------------------------- | | src | string | Yes | Path or URL to the image | | link | string | No | URL to navigate to when the image is clicked | | mode | string | No | Target for link: "_blank" (new tab) or "_self" (same tab). Default is "_self" |

Methods

| Method | Description | | ------------------------------- | -------------------------------------------------------------------- | | initialise() | Required: Sets up the carousel and returns the carousel instance | | displayItemNumber(itemNumber) | Navigates to a specific item (1-based index) | | setCycle(delay) | Enables auto-cycling with the specified delay (seconds) | | stopCycle() | Stops auto-cycling behavior |

Common Examples

Example 1: Product Gallery with Links

import { CustomImageCarousel, ImageItem } from "@pd200x/custom-image-carousel";

// Create and initialize a product gallery
const productGallery = new CustomImageCarousel({
  containerID: "product-gallery",
  imageItemArray: [
    new ImageItem({
      src: "product-front.jpg",
      link: "https://store.com/product-details",
    }),
    new ImageItem({ src: "product-back.jpg" }),
    new ImageItem({ src: "product-side.jpg" }),
    new ImageItem({
      src: "product-detail.jpg",
      link: "https://store.com/size-guide",
      mode: "_blank",
    }),
  ],
}).initialise();

Example 2: Using the Display Method

// Create and initialize the carousel
const carousel = new CustomImageCarousel({
  containerID: "image-carousel",
  imageItemArray: [
    new ImageItem({ src: "image1.jpg" }),
    new ImageItem({ src: "image2.jpg" }),
    new ImageItem({ src: "image3.jpg" }),
    new ImageItem({ src: "image4.jpg" }),
    new ImageItem({ src: "image5.jpg" }),
  ],
}).initialise();

// Navigate to the third image (index is 1-based)
carousel.displayItemNumber(3);

Example 3: Auto-Cycling Carousel with Links

// Create and initialize a carousel with auto-cycling
const autoCyclingCarousel = new CustomImageCarousel({
  containerID: "auto-carousel",
  imageItemArray: [
    new ImageItem({ src: "slide1.jpg", link: "https://example.com/page1" }),
    new ImageItem({
      src: "slide2.jpg",
      link: "https://example.com/page2",
      mode: "_blank",
    }),
    new ImageItem({ src: "slide3.jpg" }),
  ],
}).initialise();

// Set up auto-cycling with 2 second delay
autoCyclingCarousel.setCycle(2);

Browser Support

Works in all modern browsers including:

• Chrome, Firefox, Safari, Edge
• Mobile browsers (iOS Safari, Android Chrome)

Performance Tips

For optimal performance, consider these tips:

• Optimize Images: Use modern formats like WebP and properly sized images
• Height Management: Setting a fixed height for the carousel container prevents layout shifts
• Auto-cycling: Use longer intervals (2-3 seconds) for better user experience

License

ISC © Pritam Debnath