Skip to content

Super-lightweight image gallery plugin, without dependencies, bundled into one Javascript file.

License

Notifications You must be signed in to change notification settings

hellopixely/spotlight

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

18 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation


Spotlight.js

Web's most easy to integrate lightbox gallery library. Super-lightweight, no dependencies.

Demo  •  Getting Started  •  Gallery Groups  •  Options  •  Styling  •  API  •  Custom Builds

Spotlight runs out of the box:

  • No additional Javascript coding
  • No additional HTML snippets
  • No additional CSS resources
  • No additional images/assets
  • No additional handling of dynamic content and event listener

Demo: https://nextapps-de.github.io/spotlight/

Alternatively you can:

  1. use the non-bundled version of this library (classically contains css files, image files, js files)
  2. use the source files (compatible for the ES6 module system)

Features

  • Gallery groups (group images to specific galleries)
  • Gallery Tools:
    • Fullscreen
    • Zoom in/out
    • Toggle resize
    • Switch theme
    • Autoplay
    • Page
    • Title (inherits from image "alt"-attribute)
    • Description
  • Preloader
  • Prefetch next image (background task)
  • Custom options
  • Simply customize via markup (data-attributes)
  • Customizable animations
  • Custom themes
  • Controls:
    • Keyboard
    • Touch
    • Mousemove
    • Mousewheel
  • Browser history detection
  • Back-Button (Android)
  • Global API for programmatic usage

Technical properties:

  • Outstanding performance
  • Memory optimized, tiny footprint, fully cleans up
  • Event capturing (just one single global event listener)
  • Bind event listener for components dynamically:
    • install when gallery opens
    • fully cleanup when gallery was closed
  • No dependencies, no jQuery
  • Responsive
  • Super-lightweight, all in all just 6kb gzip (js + css + html + images)
  • Support for ES6 module system

Getting Started

Version Explanation

Bundle Standalone All assets bundled into one single file (js + css + html + images).
Bundle CDN Also a bundled file (js + html), but images and css will load from extern CDN.
Non-Bundled Each asset file exists separately. Recommended when extended customization is needed.

Get Latest Builds:

Bundle Standalone (6kb gzip):
spotlight.bundle.js Download https://rawcdn.githack.com/nextapps-de/spotlight/master/dist/spotlight.bundle.js

Bundle CDN (6kb gzip):
spotlight.cdn.js Download https://rawcdn.githack.com/nextapps-de/spotlight/master/dist/spotlight.cdn.js

Non-Bundled:
spotlight.min.js Download https://rawcdn.githack.com/nextapps-de/spotlight/master/dist/js/spotlight.min.js
spotlight.css Download https://rawcdn.githack.com/nextapps-de/spotlight/master/dist/css/spotlight.css
img.zip Download

ES6 Modules:
src.zip Download The folder "src" of this Github repository.

Alternatively when using non-bundled version you can download images from /dist/img/.

Get Latest (NPM):

npm install spotlight.js

Get Latest (ES6 Modules):

https://github.com/nextapps-de/spotlight/tree/master/src

Setup Spotlight

1. Just insert the script resource tag right after the documents head:

When you need to add custom styling through css class modifications it is recommended to load the library before you load the css. Otherwise you have to add an "!important" flag to override existing styles.

<html>
<head>
    <script src="spotlight.bundle.js"></script>
    <title></title>
</head>
<body>
    <!-- CONTENT -->
</body>
</html>

2. and add the class spotlight to an anchor element accordingly, e.g.:

<a class="spotlight" href="img1.jpg">
    <img src="thumb1.jpg">
</a>
<a class="spotlight" href="img2.jpg">
    <img src="thumb2.jpg">
</a>
<a class="spotlight" href="img3.jpg">
    <img src="thumb3.jpg">
</a>

This also works with dynamically loaded content. There is no need to inject listeners on new elements. Instead Spotlight make use of global event capturing.

Alternatively you can also use the Spotlight API for programmatically use.

Gallery-Groups

Give one of the outer wrapping element the class spotlight-group, e.g.:

<div class="spotlight-group">
    <a class="spotlight" href="dog1.jpg">
        <img src="dog1-thumb.jpg">
    </a>
    <a class="spotlight" href="dog2.jpg">
        <img src="dog2-thumb.jpg">
    </a>
    <a class="spotlight" href="dog3.jpg">
        <img src="dog3-thumb.jpg">
    </a>
</div>
<div class="spotlight-group">
    <a class="spotlight" href="cat1.jpg">
        <img src="cat1-thumb.jpg">
    </a>
    <a class="spotlight" href="cat2.jpg">
        <img src="cat2-thumb.jpg">
    </a>
    <a class="spotlight" href="cat3.jpg">
        <img src="cat3-thumb.jpg">
    </a>
</div>

Options

Pass options as declarative via data-attributes in the HTML markup or use the Spotlight API.

When using markup follow these style: data-option="value" (change option and value accordingly), e.g.: <a class="spotlight" data-preftech="false"></a>.

You can either apply the following data-attributes to the spotlight-group wrapper element or apply them separately to each spotlight anchor element (that also overrides group definitions).

Option         Values Description
index number Sets the starting index when showing the gallery by using the Spotlight API
animation "fade"
"slide"
"scale"
"flip"
Change animation (use built-ins)

Note: could also combined as comma-separated list, e.g: data-animation="slide,fade,scale" (this is the default animation).
control string Show/hide control elements as "whitelisted" through a comma-separated list, e.g. data-control="reset,page,fullscreen"
autohide true / false / number Enable/disable automatically hide controls when inactive, also set cooldown time
fullscreen true / false Show/hide fullscreen button
zoom true / false Show/hide both zoom buttons
zoomin true / false Show/hide zoom-in button
zoomout true / false Show/hide zoom-out button
reset true / false Show/hide reset button
theme true / false Show/hide theme button
player true / false / number Show/hide player button, also set delay between each tick
infinite true / false Restart from beginning when no slides left
theme "white"
"dark"
Change the default theme
page true / false Show/hide page
title string / false Set image title or hide it

Note: When using image elements, this attribute will also inherit automatically from <img alt="...">. To prevent this behavior you can set data-title="false". This will hide the title regardless of any image alt-attributes.
description string / false Set image description or hide it
preloader true / false Enable/disable preloading of the current image (also hides spinner)
prefetch true / false Enable/disable preloading of the next image

Example:
<div class="spotlight-group" data-title="Untitled" data-animation="fade"
     data-fullscreen="false" data-maximize="false" data-minimize="false">
    <a class="spotlight" href="cat1.jpg" data-title="This is a title.">
        <img src="cat1-thumb.jpg">
    </a>
    <a class="spotlight" href="cat2.jpg" data-description="This is a description.">
        <img src="cat2-thumb.jpg">
    </a>
    <a class="spotlight" href="cat3.jpg">
        <img src="cat3-thumb.jpg" alt="This is a title.">
    </a>
</div>

Hint: The 2nd image gets the title "Untitled" from the group attributes.

Control elements could also whitelisted as a comma-separated list, e.g.:

<div class="spotlight-group" data-control="fullscreen,autofit,theme">

Use a whitelist to enable controls gets priority over other ambiguous options.

The same from above as explicitly:

<div class="spotlight-group" data-fullscreen="true" data-contrast="true"
     data-zoomin="false" data-zoomout="false" data-reset="true">

When control attributes are not specified they are automatically enabled by default.

Therefore the example above could be shortened to:

<div class="spotlight-group" data-zoomin="false" data-zoomout="false">

Since "zoom" is a shorthand for both zoom buttons, this is the same:

<div class="spotlight-group" data-zoom="false">

Spotlight API

Also you can programmatically use Spotlight via the library API. This way does not require any dependant HTML elements (e.g. the classname "spotlight").

Define a gallery group as follows:

var gallery = [{
    title: "Image 1",
    description: "This is a description.",
    src: "gallery/london-1758181.jpg"
},{
    title: "Image 2",
    description: "This is a description.",
    src: "gallery/sea-1975403.jpg"
},{
    title: "Image 3",
    description: "This is a description.",
    src: "gallery/newport-beach-2089906.jpg"
}];

Show gallery with default options:

Spotlight.show(gallery);

Show gallery with custom options:

Spotlight.show(gallery, {
    index: 2,
    theme: "white",
    autohide: false,
    control: ["autofit", "zoom"]
});

Close gallery:

Spotlight.close();

Next slide:

Spotlight.next();

Previous slide:

Spotlight.prev();

Goto slide:

Spotlight.goto(3);

Zoom to:

Spotlight.zoom(1.5);

Toggle theme:

Spotlight.theme();

Set theme:

Spotlight.theme("white");
Spotlight.theme("dark");

Toggle fullscreen:

Spotlight.fullscreen();

Set fullscreen:

Spotlight.fullscreen(true);
Spotlight.fullscreen(false);

Toggle autofit:

Spotlight.autofit();

Set autofit:

Spotlight.autofit(true);
Spotlight.autofit(false);

Toggle menu:

Spotlight.menu();

Set menu:

Spotlight.menu(true);
Spotlight.menu(false);

Example ES6:

import Spotlight from "./spotlight.js";

Spotlight.show(
    [ /* Gallery */ ], 
    { /* Options */ }
);

Custom Styling

To add custom styling just override CSS classes accordingly:

#spotlight {
    /* font styles, background */
}
#spotlight .title{
    /* image title */
}
#spotlight .description{
    /* image description */
}
#spotlight .page{
    /* current page */
}
#spotlight .fullscreen{
    /* button fullscreen */
}
#spotlight .autofit{
    /* button autofit */
}
#spotlight .zoom-out{
    /* button zoom out */
}
#spotlight .zoom-in{
    /* button zoom in */
}
#spotlight .theme{
    /* button theme */
}
#spotlight .player{
    /* button autoplay */
}
#spotlight .close{
    /* button close */
}
#spotlight .arrow-left{
    /* button arrow left */
}
#spotlight .arrow-right{
    /* button arrow right */
}

Themes

Customize builtin themes

Uae the same classes as above:

#spotlight.white .title{
    /* image title in white theme */
}
#spotlight.dark{
    /* main background in dark theme */
}

Create New Themes

Define styles, e.g. for the custom theme name "my-theme":

#spotlight.my-theme .title{
    /* image title in custom theme */
}
#spotlight.my-theme{
    /* main background in custom theme */
}

Apply custom theme via markdown:

<a class="spotlight" href="img.jpg" data-theme="my-theme">
    <img src="thumb.jpg">
</a>

Or apply custom theme via API:

Spotlight.show([ /* Gallery */ ],{
    theme: "my-theme"
});

Advanced Recommendations

It is very common to load the library right before the closing body tag of your document. In rare situations it might produce a short flashing/reflow after page load, depending on your stack. Moving the script tag into the head section will solve this issue.

If you like to override css classes for custom styling you may need to add "!important" flag to the css property value.

<html>
<head>
    <title></title>
</head>
<body>
    <!-- 
    CONTENT 
    -->
    <script src="spotlight.bundle.js"></script>
</body>
</html>

Custom Builds

Note: You can modify all source files e.g. stylesheets, template and also the images files located in /src/img/. Providing a more handy way to pass custom images is coming soon.

Perform a full build:

npm run build

The destination folder of the build is: /dist/


Copyright 2019 Nextapps GmbH
Released under the Apache 2.0 License

About

Super-lightweight image gallery plugin, without dependencies, bundled into one Javascript file.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • JavaScript 77.5%
  • CSS 12.4%
  • HTML 10.1%