Heart Slider

An elegant slideshow

Purpose

Built for image-forward websites, HeartSlider is a simple and elegant slideshow that is designed for developers. It is adaptable, and customizable — with just enough styling to blend into any design system.

Getting Started

Make sure to include heartslider.min.js and heartslider.min.css files to your project. You can either download and add to them to your project’s directory, or use a CDN like jsDelivr.

<script defer src="https://cdn.jsdelivr.net/npm/heartslider@latest/dist/heartslider.min.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/heartslider@latest/dist/heartslider.min.css">

Then, add your markup.

<div class="heart-slideshow">
	<div class="heart-slide">
		<figure class="image-holder">
			<img 
				data-sizes="(min-aspect-ratio: 1/1) 100vw, 140vw" 
				data-src="img/image-01.jpg" 
				data-srcset="img/image-01.jpg 1x, img/image-01@2x 2x" 
				alt="" />
		</figure>
	</div>
	...
</div>

Finally, initiate the slideshow with a new HeartSlider class and set your options in your javascript file.

new HeartSlider({
	slideshow: ".heart-slideshow",
	slides: ".heart-slide",
	transition: 3000,
	delay: 1000,
});

Default Options

new HeartSlider({
	slideshow: ".heart-slideshow",
	slides: ".heart-slide",
	transition: 3000,
	manualTransition: 200,
	delay: 1000,
	loop: true,
	randomize: false,
	paused: false,
	effect: "fadeOut",
	buttons: false,
	swipe: true,
	clickToAdvance: false,
	pauseOnInactiveWindow: false,
	progressIndicators: {
		type: "dash", // or "dot"
		clickable: true,
		color: "#fff",
	},
});

Actions

Declare the slideshow as a constant, then run pause() or resume() to stop or start autoplay. Use the next(), prev(), and goTo(𝑥) methods to manually advance the slideshow. Use destroy() to remove everything and reset the DOM.

const myHomepageSlideshow = new HeartSlider();
					
// Pause
myHomepageSlideshow.pause();
// Resume
myHomepageSlideshow.resume();

// Next Slide
myHomepageSlideshow.next();
// Previous Slide
myHomepageSlideshow.prev();
// Jump To Certain Slide
myHomepageSlideshow.goTo(𝑥);

// DESTROY
myHomepageSlideshow.destroy();

Events

Currently, there are three callback events that you can use to hook into the slideshows. The transitionStart event will happen immediately as a new slide begins to transition in, the transitionEnd will happen at the end of that transition, and the firstImageLoad event will trigger when the image in the first slide finishes loading.

const myHomepageSlideshow = new HeartSlider();
					
// Events
myHomepageSlideshow.on("transitionStart", function (slideshow, slideshowElement, currentSlide) {
	/* Code that runs on the START of each new slide goes here */
	console.log({ slideshow }, { slideshowElement }, { currentSlide });
});
myHomepageSlideshow.on("transitionEnd", function (slideshow, slideshowElement, currentSlide) {
	/* Code that runs at the END of each transition goes here */
});
myHomepageSlideshow.on("firstImageLoad", function (slideshow, slideshowElement, currentSlide) {
	document.body.classList.add("remove-intro");
});

All Options

optiondescriptionvalue typedefault value
slideshow

The parent element that contains your slides. By default, this will automatically init on the first element on the page with a class of "heart-slideshow".

String or querySelector
(querySelectorAll is not supported)

".heart-slideshow"
slide

The classname of the elements that contain your content. If left blank, it will look for elements with the "heart-slide" class.

String

".heart-slide"
transition

The duration of the fade effect.

Number, in milliseconds.

3000
manualTransition

The duration of the fade effect during a swipe or click.

Number, in milliseconds.

200
delay

The amount of time to wait before starting the transition to the next slide.

Number, in milliseconds.

1000
loop

Tells the slideshow to restart at the beginning once reaching the final slide.

Boolean

true
randomize

Selects a random slide to start from. Does not shuffle the order of slides.

Boolean

true
paused

If set to true, the slideshow will not auto-play.

Boolean

false
effect

Two options for the easing applied to the fade. Using fadeOut will smoothly crossfade from one slide to the next. Using fadeInOut will make the current slide completely fade out before fading in the new one.

String;
fadeOut or fadeInOut

"fadeOut"
buttons

If true, will create previous / next buttons using the heart-prev and heart-next classes. Buttons can be customized with CSS.

Boolean

false
swipe

Allows the slideshow to be manually controlled with swipe gestures on touch devices.

Boolean

true
clickToAdvance

Allows the slideshow to be manually advanced with a click or tap.

Boolean

false
pauseOnInactiveWindow

Will pause the slideshow while the website is not in the active window.

Boolean

false
progressIndicators

Adds markers at the bottom of the page to show the slideshow progress.

Object

{
type: "dot",
clickable: true,
color: "#fff",
}