diapositive
v1.14.1
Published
Diapositive is a dependency-free Javascript slideshow helper library. It does only one thing but does it well: toggling a class between slides in a deck.
Downloads
49
Readme
Diapositive
Diapositive is a dependency-free Javascript slideshow helper library. It does only one thing but does it well: toggling a class between slides in a deck.
Set up some markup, create a new Diapositive instance and you're ready to make incredible slideshows in seconds.
Philosophy
As my coding style evolves, I tend to prefer simpler, to the point libraries that make life as a developer a little easier without overcomplicating things. This is why after spending hours replicating code from project to project, I began compiling some functionalities into their own self contained modules. Hopefully, this is the beginning of a series of lightweight, easy and perfomant libraries to save me and everyone else time and effort across projects.
What does it do? Why should I use Diapositive instead of x or y?
The idea behind this library is to provide the minimum boilerplate code to quickly bootstrap interesting slideshow components.
It is only concerned with how things should work, not how they should look. By providing a tiny API surface, this library aims to simplify slideshow development to let you spend more time on styling or more valuable features.
Of course, you could use more advanced libraries to achieve the same thing. But why use a fully-fledged animation library when all you need is a simple toggling mechanism?
Why use a library at all? While the logic behind this one is rather simple, I found that replicating it multiple times a week gets cumbersome really quickly.
Example
You can find a simple usage example in the example folder of this repository. I encourage you to play with it to get a feel of what the library is doing.
WARNING: You must build the project with npm run build before viewing the example.
Getting started
Download latest version with NPM...
npm install diapositive
(you can also link to the lib in html head with unpkg: <script src="https://unpkg.com/diapositive@latest/dist/diapositive.js"></script>
)
...then create some markup...
<ul>
<li>Julien</li>
<li>André</li>
<li>Marcel</li>
</ul>
<button id="prev">Previous</button>
<button id="next">Next</button>
...and finally initialize Diapositive.
import Diapositive from 'diapositive';
const diapo = new Diapositive('ul');
document.getElementById('prev').onclick = diapo.prev;
document.getElementById('next').onclick = diapo.next;
You're all set! Now Diapositive will take care of adding an active
class to the correct element.
<ul>
<li class="active">Julien</li>
<li>André</li>
<li>Marcel</li>
</ul>
...Next button clicked...
<ul>
<li>Julien</li>
<li class="active">André</li>
<li>Marcel</li>
</ul>
Note: The selector can be either a string or a node, ie:
'ul'
anddocument.querySelector('ul')
will work exactly the same.
API
Diapositive exposes these methods to navigate between slides:
| Method | Description |
| ------------------------- | ----------------------------------------------------------------------------- |
| Diapositive.next()
| Go to next slide. If current slide is last slide, go to first slide. |
| Diapositive.prev()
| Go to previous slide. If current slide is first slide, go to last slide. |
| Diapositive.goTo(index)
| Go to slide at given 0 based index. |
| Diapositive.start()
| Start Diapositive autoplay. Time is configurable via Diapositive.time option. |
| Diapositive.stop()
| Stop Diapositive autoplay. |
Events
Diapositive.on(event, callback)
Currently Diapositive only supports the change
event. It triggers at the beginning of a slide change via prev
, next
, goTo
or if the autoPlay
option is set to true
.
The current diapositive index is passed to the callback function.
diapositive.on('change', (index) => {
console.log('Slide changed to:', index);
});
// Equivalent
diapositive.onchange = index => console.log('Slide changed to:', index);
Options
Diapositive takes an optional options
object. If none is specified, reasonable defaults are used.
| Option | Type | Default | Description |
| ----------------- | --------- | -------- | ------------------------------------------------------------------------------ |
| autoPlay
| boolean
| false
| If the Diapositive instance should loop automatically |
| activeClassName
| string
| active
| The className added to the active slide |
| prevClassName
| string
| | The className added to the previous slide |
| nextClassName
| string
| | The className added to the next slide |
| startAt
| number
| 0
| The first focused slide when a new Diapositive instance is created (0 indexed) |
| time
| number
| 2000
| Delay between slides if autoplay is set to true |
Styling
As intended, this library only provides minimal functionality. You are responsible for everything styling related.
The simplest example would be something like this:
ul li {
display: none;
}
ul li.active {
display: block;
}
To get more control, you should probably overlay all your slides with position absolute in a fixed height container. That way, you will be able to stage great css animations with minimal effort.
<ul class="diapo">
<li class="diapo__slide">1 – My first slide</li>
<li class="diapo__slide">2 – My second slide</li>
<li class="diapo__slide">3 – My third slide</li>
<li class="diapo__slide">4 – My fourth slide</li>
</ul>
import Diapositive from 'diapositive';
const diapo = new Diapositive('.diapo', {
className: 'diapo__slide--active',
autoPlay: true,
time: 3000
});
.diapo {
height: 100vh;
width: 100vw;
position: relative;
margin: 0;
padding: 0;
}
.diapo__slide {
position: absolute;
top: 0;
bottom: 0;
left: 0;
right: 0;
display: flex;
align-items: center;
justify-content: center;
font-weight: bold;
font-size: 4rem;
/* Animation */
transition: 0.3s all;
opacity: 0;
transform: scale(0.8);
pointer-events: none;
}
.diapo__slide--active {
opacity: 1;
transform: scale(1);
pointer-events: auto;
}
Note the use of the pointer-events
css property. As your slides will sit on top of each other, you need to make sure that the user can only interact with the current slide only.