A minimal JS library for showing & hiding things

  • By Pedro Duarte
  • Last update: Sep 14, 2022
  • Comments: 15

wallop

Build Status npm version

Much more than just a slider

wallop is a minimal 4kb library for showing & hiding things.

❗️ Important note
Version 1 of WallopSlider is not compatible with version 2+.
If you are still using v1, please note that I am no longer supporting it.
Documentation, etc. has been moved to this branch.

About

In a nutshell, wallop takes a collection of HTML elements and Previous & Next buttons, and adds helper HTML classes in the correct elements based on whether you want to navigate forwards or backwards.

It basically just add the right classes in the right places at the right time.

With those classes, you can do an infinite number of things, controlling what's shown or hidden with CSS.

Examples

I've created a collection on Codepen with a few more examples, go take a 👀 !

Benefits

  • Mobile first
  • Progressive enhancement
  • Transitions/Animations are all in CSS
  • Minimal JavaScript
  • Flexible & Scalable
  • Custom events and API available
  • 4KB minified
  • Dependency free

Install

With npm

$ npm install wallop

With bower

$ bower install wallop

Download
You can download the latest version or checkout all the releases here.

Usage

Once you have downloaded Wallop, the first thing you need to do is include the CSS and the JavaScript.

CSS

">
<head>
  <link rel="stylesheet" href="path/to/wallop.css">
head>

JavaScript

">
<script src="path/to/Wallop.min.js">script>
<script>
  var wallopEl = document.querySelector('.Wallop');
  var slider = new Wallop(wallopEl);
script>

commonJS

  var Wallop = require('Wallop');

ES6

  import Wallop from 'Wallop';

HTML

">
<div class="Wallop">
  <div class="Wallop-list">
    <div class="Wallop-item">div>
    <div class="Wallop-item">div>
    <div class="Wallop-item">div>
    <div class="Wallop-item">div>
    <div class="Wallop-item">div>
  div> <button class="Wallop-buttonPrevious">Previousbutton> <button class="Wallop-buttonNext">Nextbutton> div>

#protip
You can set the starting slide with a .Wallop-item--current class.

Adding animations

Wallop has no animations by default, so if you want to animate the slides, you need to extend the default .Wallop class with an animation modifier and include the respective CSS into your HTML.

I have created a few basic animations which are ready for you to use out-of-the-box, you will find them in the /css directory.

Including animation CSS

">
<head>
  <link rel="stylesheet" href="path/to/wallop.css">
  <link rel="stylesheet" href="path/to/wallop-animation.css">
head>

Extending with modifier

...
">
<div class="Wallop Wallop--fade">
...
div>

Available animations

Here's a list of the available animation modifiers ready for you to use

  • Wallop--slide
  • Wallop--fade
  • Wallop--scale
  • Wallop--rotate
  • Wallop--fold
  • Wallop--vertical-slide

protip
These animation helpers are especially helpful using if you are using wallop as a slider, but don't feel forced to use them, instead, feel free to take advantage of the classes wallop provides you with, and create you own!

Options

Here's a list of options you can pass to Wallop

  • buttonPreviousClass: 'Wallop-buttonPrevious'
  • buttonNextClass: 'Wallop-buttonNext'
  • itemClass: 'Wallop-item'
  • currentItemClass: 'Wallop-item--current'
  • showPreviousClass: 'Wallop-item--showPrevious'
  • showNextClass: 'Wallop-item--showNext'
  • hidePreviousClass: 'Wallop-item--hidePrevious'
  • hideNextClass: 'Wallop-item--hideNext'
  • carousel: true

API

Wallop offers a basic API for you to use, so you can control it from your own buttons or gestures.

goTo(index)

This allows you to go to a specific slide index.

var slider = document.querySelector('.Wallop');
var Wallop = new Wallop(slider);

// Go to 2nd slide
Wallop.goTo(1);

#protip
index starts at 0 👌

next()

This allows you to go to the next slide

var slider = document.querySelector('.Wallop');
var Wallop = new Wallop(slider);

// Go to next slide
Wallop.next();

previous()

This allows you to go to the previous slide

var slider = document.querySelector('.Wallop');
var Wallop = new Wallop(slider);

// Go to previous slide
Wallop.previous();

reset()

This resets all internal variables of Wallop. Useful when dynamically changing the number of items in your slider.

var slider = document.querySelector('.Wallop');
var Wallop = new Wallop(slider);

// Some function that will dynamically
// insert new itmes in Wallop
insertNewItems();

// Reset config
Wallop.reset();

Events

Wallop dispatches a Custom Event every time a slide changes, and it returns a detail object which contains the current slide index and the element you initiated Wallop with.

Listening to a slide change

// event.detail.currentItemIndex // => number }; // Listen to the handler Wallop.on('change', handler); // Remove the handler listener Wallop.off('change', handler);">
var slider = document.querySelector('.Wallop');
var Wallop = new Wallop(slider);
var handler = function(event) {
  // event.detail.wallopEl
  // => 
  
// event.detail.currentItemIndex // => number }; // Listen to the handler Wallop.on('change', handler); // Remove the handler listener Wallop.off('change', handler);

Real life examples

  • Google – uses wallop as a slideshow, transitioning the background colour and animating the hero image of each item
  • Warp – uses the power of wallop's API and Custom Events to control the items via the URL and to build a custom pagination
  • Strava Insights – uses wallop a a slideshow, transitioning and transforming the background images with delay

If you are using wallop, please do let me know by creating an issue and I'll make sure to add it to this list 👊

Limitations

Due to its simplicity, wallop has a few limitations. For example, it is not possible to have the slide position animation based on gesture, or it's not possible to include physics based animations based on gesture momentum.

If you want a slider which provides all these options, I highly recommend David Desandro's Flickity.

Contributing

Plese see CONTRIBUTING.md for more information.

Licensing

MIT © 2018 Pedro Duarte

Github

https://github.com/peduarte/wallop

Comments(15)

  • 1

    Uncaught (in promise) Error

    The error is An instance of Wallop with this selector already exists. I am using Wallop in my FeathersJS app and I am dynamically generating my UI with JavaScript. I instantiate Wallop in my render code and it everything works well. When I leave the tab and go back to it, I see this error and my slides are nowhere to be found.

    I'm just referencing the wallop.min.js file. Should I be using npm instead (if so, how do I use it in the frontend)?

    ~~EDIT: Adding the Wallop-item--current class to the first item in my carousel makes it at least look presentable when the Wallop instance breaks...which gives me an idea, brb.~~

    Alright, turns out that if I just comment out

    for (var i = 0; i < selectorPool.length; i++) {
      if (selectorPool[i] === selector) {
        throw new Error('An instance of Wallop with this selector already exists.');
      }
    }
    

    in the unminified version of Wallop and use that, I don't run into any issues. I'm running with that.

  • 2

    Issue in IE

    Thanks for making this, it's great. However I ran into the following issue when implementing today and wondering if you have some thoughts?

    {exception} Object doesn't support this action
    

    and it points to:

    WallopProto.createCustomEvent = function () {
        var _this = this;
        this.event = new CustomEvent('change', {
          detail: {
            parentSelector: _this.selector,
            currentItemIndex: Number(_this.currentItemIndex)
          },
          bubbles: true,
          cancelable: true
        });
      };
    
  • 3

    Use visibility to hide element from pointer events

    Re: https://css-tricks.com/snippets/css/toggle-visibility-when-hiding-elements/

    Basically I used Wallop, it was awesome, but I couldn't select the content of the currently viewed item. I used visibility: hidden to hide the element. This means the user can interact with the currently viewed item but still allow the item to transition to the next item.

    Fixes #56 and #54.

  • 4

    Implement Autoplay Option

    Implement an autoplay option (e.g. called autoPlay), which is a boolean that says whether the slider should slide automatically. There should also be another option (e.g. called interval), which is an integer that says after how many ms the slide should change when autoplay is enabled. That would be really cool :-)

    Thanks for your work!

  • 5

    Add bower.json

    Created initial version of bower.json, as mentioned in issue #77. Bower.json is based on the projects package.json and the official spec. Both .js (unminified) and .css are included in main, so a fully working copy of Wallop will be available if these files are picked.

  • 6

    Fix the `carousel` option

    • Detect the correct direction in the goTo function to set the correct classes.
      • To detect a forwards direction we need to check if the index is higher than the currentItemIndex or if the index is 0 an the currentItemIndex is the index of the last item (go from the last item to the first).
      • To detect a backwards direction we need to check if the index is lower than the currentItemIndex or if the index is the index of the last item and the currentItemIndex is 0 (go from the first item to the last).
    • Fix the initial button state when the carousel option is disabled.
  • 7

    Issue in Firefox

    I have also noticed that in Firefox it doesn't like it when setAttribute only has one argument i.e.

    buttonNext.setAttribute("disabled");
    

    throws the following error:

    TypeError: Not enough arguments to Element.setAttribute.
    

    changing to the below removes the error:

    buttonNext.setAttribute("disabled","disabled")
    
  • 8

    Store "direction"

    In order to have proper circular animations (sliding carousel) we need to know if the user is navigating forwards or backwards.

    A direction variable must be implemented to store the direction value. This will ensure the correct classes are added to the next or previous items based on the direction of the user.

    If anyone is willing to take this up and need more info, let me know. Otherwise, I'll crack on with this as soon as I do.

    Will assign it to myself if i start progress.

    ✌️

  • 9

    Bug in slide animation in Google Chrome on Mac OS

    See for yourself - video, pictures move asynchronously in Google Chrome. Tested on Mac OS 10.8.2 and 10.9.3. I know that this is a bug in Google Chrome on Mac OS, but my english is pretty bad, so can you do a proper bugreport about this to Chromium project?

  • 10

    How about multiple columns?

    Current version has one column. Sometimes we need two or more columns in carousel and even we need different column count when responsive.

    Do you plan to add multiple columns feature?

  • 11

    Add update method

    Related to #69 I've added an update method which sets correct state of global variables after changing slider content. Can you do a quick review? Isn't against the wallop philosophy? I was also wondering about calling the method in the upper initialization part to save some lines of code. (but the name should be slightly different then)

  • 12

    Consuta Blancos entre distintas imagenes;

    Buenas tardes

    He utilizado la librería para hacer un slider de imágenes de forma dinámica realizando la carga de imágenes mediante Post y a pesar de controlar la cantidad y resolución en la subida introduce imágenes en blanco cuando intento introducirlas mediante Jquerys cuando el numero de imágenes introducidas es muy grande.

    Agradecería cualquier ayuda, guía o idea que pudiera orientarme para resolver mi problema.

    Un saludo

  • 13

    Fix slide CSS animation for safari browser

    according to my created issue: https://github.com/peduarte/wallop/issues/88

    wondering why the CSS animation was quite a bit complex with that 99% opacity and translate3d stuff... 🧐 I just did with that left property and it works well in Chrome, FF, IE11, Samsung Browsers.

  • 14

    Slide effect in Safari not nice

    In Safari the slide effect isn't very nice:

    https://codepen.io/AndreKelling/pen/NoGQQr

    Images just appear complete once they are fully slided in.


    Safari: Version 12.0.2 Wallop: https://rawgit.com/peduarte/wallop/master/js/Wallop.min.js

  • 15

    Can't resolve 'Wallop’ when building on linux

    I just received this error while trying to build on a linux machine.

    ERROR in ./src/js/slider.js
    Module not found: Error: Can't resolve 'Wallop’ in
    

    I fixed it by changing to lowercase ‘wallop’ like it is referenced in node_modules. Normally I build on a mac without issues. Can you update the documentation?