Story Show Gallery View demo gallery

Story Show Gallery

Javascript vertical gallery created by Roman Flössler
Known Vulnerabilities

SSG nicely combines photos and captions to show a whole story in full ­screen, mini­­mal­ist, non-dis­tracting environ­­ment. SSG will support your brand and mar­ket­ing. The gallery is vertical - optimized for use on smart­phones.

Download SSG: GitHub - NPM - Wordpress plugin

Story Show Gallery versus usual gallery lightbox. SSG can utilize whole smartphone display - even notch area. usual gallery lightbox
SSG versus usual gallery lightbox. Do you want more icons or more from a photo? Story Show Gallery can use whole smartphone display - even notch area.

Your photos in the main role

Give your photos maximum space with responsive SSG full screen lightbox. There are no ugly arrows ←→ next to a photo, vertical slider and cur­sor are subtle.

On smartphones, full screen mode works like on You­Tube. It activa­tes after rotating a phone into landscape mode.

The gallery doesn't have an icon for full screen mode. I did a little research and users simply don't use it. So it's up to you, if the gallery will go into full screen.

Neverending story

Behind the last image Story Show Gallery can load a HTML signpost to other photo galleries. See a sample signpost behind ssg

Browsing without clicking and thinking

Scrolling is the most natural interaction with a webpage. Story Show Gallery works like Facebook - as a user scrolls down new pictures are constantly loading.

Story Show Gallery is vertical and therefore great for use with mobile phones. In portrait mode a user usually sees a part of the next photo, so he keeps scroll­ing to see it whole.

Brand building and social sharing

SSG can display your logo or some text (emoji) over images. You can configure it in the SSG settings. photo watermark

Social sharing icon is not put aside, it is part of a content, but subtle. A spectator's eyes will literally crash into the share icon at the end of a caption or in the corner of a photo. It can be disabled in the settings. social share icon

You can deep link into the gallery to show a part­icular pict­ure. Just use image name in the hashtag: deep linking

Complete your photos with captions

With captions you can tell the whole story behind pictures or amuse a spec­tator with some fun fact.

Google treats captions as a text content. Especially when you haven't much text on your page, captions will help a lot your page to rank higher in Google search.

SSG is probably the only gallery which can place each caption individually according to image size vs. screen size. It is really important on smartphones.

SSG is fully responsive - it compares image size vs. screen size and place a caption to an optimal position.

Easy implementation

SSG has very easy setup, it binds onto image hyper­links on the page auto­mati­cally. You can control this proccess by CSS classes. Define sepa­rate galleries, activate full screen mode, selectively deactivate SSG, etc.

There are 3 ways how a photo gallery can be created. Auto­matically from images on the page, by passing an array of images into SSG, or by combi­nation of both.

No e×it mode: You can write just minimal HTML code and SSG will crea­te a vertical gallery which behaves like a simple webpage. Because there is not much to dis­play without SSG, the gallery can run in the no e×it mode.

Story Show Gallery supports Goo­gle analytics to measure views of each photo. SSG optionally detects and uses GA tracking code on your site. Google Analytics


You can use Story Show Gallery freely within open source GNU GPL-3.0 license.
There is one exception from the license: Distributing Story Show Gallery within a Wordpress plugin or theme is only allowed for the author of Story Show Gallery.

Implementation and configuration

All you need to do, is add ssg.min.css and jQuery in the <head> of the document and ssg.min.js before </body>.

You can link files directly from CDN (faster loading), just copy these lines into your HTML:

<link rel="stylesheet" href="">

// SSG requires jQuery library at least in version 1.5
<script src=""> </script>

<script src=""> </script>

Story Show Gallery looks for all hyper­links (<a> tags) on the page that points to a picture file (extensions: jpg, jpeg, JPG, png, PNG, gif, GIF, webp). And adds to all these hyper­links an onclick function which runs the gallery. Unless nossg class is used.

A photo caption a is taken from a thumbnail's alt att­ribute or a link text. You can also add author's name - enter it into data-author attribute of hyperlink. SSG will create a gallery from all these three images (BigImage1~3):

<a href='BigImage1.jpg'> <img alt='text caption' src='thumb.jpg'> </a>
<a href='BigImage2.jpg data-author='photo by…''> Another caption </a>
<a href='BigImage3.jpg'></a> (an empty link, no caption)
// Hyperlinks with <Picture> tag inside are also supported.

Default SSG configuration and language localization is at the begining of ssg.js file. Settings are com­mented. You can edit settings in ssg.js file and then minify it. Or copy selected settings into your HTML to override default config­uration. Place it after ssg.min.js, as it is shown on the following picture.
Complete example of SSG implementation and configuration:

HTML5 example of SSG implementation

SSG files and minifying

Story Show Gallery consists of three files placed in the src directory:

There are minified files in the dist directory ready for deployment on your website. If you modify source files, you may want to minify the result. Use existing npm script:

npm install // it will install uglify-JS and uglify-CSS npm modules which are needed for minifying
npm run-script dist // it will minify the source files and put them into the dist directory.

Controling SSG by CSS classes

By default SSG will make one big gallery from all linked images on the page. CSS classes can change this behaviour. There are nine classes: ssg, nossg, gossg, vipssg, fs and four themes. Classes have to be assigned to a hyper­link tag or to any tag which contains image hyper­links - they all will be affected:

<a href='outsideImg.jpg' class='fs' > caption </a>
<section class='ssg fs vipssg ssgblack'>
    <a href='insideImg.jpg'> caption </a>
  <a href='insideImg2.jpg'> caption </a>

The ssg class creates a separate gallery, assign it to some parent element of many picture hyper­links. In the gallery will show only the pictures that are inside the element with the ssg class. Outside images creates a gallery with id#0.

The fs class will activate full screen mode.

Image hyperlinks that aren't part of any separate gallery, will bind to the gallery (or hyperlinks) with vipssg class. So that they won't display alone.
If you click on the outsideImg.jpg hyperlink, it will display in the gallery together with inside images. But when you click on some inside image hyperlink, only images inside section.ssg will display in the gallery.

SSG will ignore image hyperlinks (or the whole gallery) with nossg class. Images will open normally into browser's tab.

Image linked with the gossg class can be only an initial image of the gallery. If a user want to see it and clicks on it. Otherwise image linked with gossg class won't show in the gallery.

SSG offers four themes and each has its own class, which you can assign to some gallery:
light theme -> class: ssglight, dim theme -> class: ssgdim, dark theme -> class: ssgdark and black theme -> class: ssgblack.

Gallery events

SSG offers four gallery events, you can use them to run your functions. SSG events are part of the configuration.

  1. SSG.cfg.onGalleryStart fires after creating a gallery
  2. SSG.cfg.onImgChange fires on every image change (even the first one)
  3. SSG.cfg.onSignpost fires when a user reach the HTML signpost after photos or if he scrolls after the final menu
  4. SSG.cfg.onGalleryExit fires on the gallery exit

SSG.cfg.onGalleryStart = function(data) { console.log( data.imgCount + ' images in the gallery. Starting with image: ' + data.imgName); }; // data object: data.imgCount // count of images in the gallery data.imgGalleryId // ID of current Image in the gallery data.imgPageId // ID of current image on the page data.GalleryId // ID of a gallery which belongs to initial image data.imgPath // whole path to current image data.imgName // image name of current image (no extension) data.imageCaption // image caption for current image // if signpost is diplayed, data object is null

You can find complete example in the source code of this page (at the end). It writes a little statistic of the gallery usage into the JS console.

Order of photos in the gallery

The picture a user clicked on is shown first, then Story Show Gallery displays following pictures and then the rest. Example: A user clicked on the fourth picture. Pictures are shown in the following order - 4,5,6,7 and then it continues with picture 1,2,3.
If a picture is part of a separate gallery (.ssg class), SSG prefers to show first three pictures of a gallery together. Example: if a user click on the third image, the order of images in the gallery will be 3,1,2,4,5,6. This behaviour can be deactivated in the settings.

Deep linking into Story Show Gallery

SSG can be initiated by a link with photo's name in a hashtag. For example this link will activate Story Show Gallery and show the photo named fifth-element. It is enough to have in the hashtag crucial part of the name - #element.

An address of each photo is shown in a browser’s navi­gation bar while browsing through the gallery. In full screen mode you can get a picture address via social share icon.

Vertical scrolling through the gallery

There are two options. Classic vertical scrolling with scrollbar or finger. And then jump scroll. A mouse wheel and arrow keys have an altered function, they scroll from one image to next image.

Move to the next image:
mouse wheel, down arrow key, right arrow, PgDn key or spacebar.
Move to the previous image:
mouse wheel, up arrow key, left arrow, or PgUP key.

For touch screens there are two invisible areas: the top and bottom half of the screen. After tapping somewhere into the bottom (top) half, SSG jump scroll to the next (previous) picture. method

You can run the gallery by Javascript calling method. Example: the body's onload event runs the gallery immediately after a page is loaded:

<body onload=''>

The fs:true parameter will activate full screen mode. Use the fsa parameter instead, if the gallery is initiated without an active click from a user. That active click is needed for entering fullscreen mode. The fsa para­meter will ask if a user wants to switch into fullscreen mode.

<a onclick='{fs:true})'> Show gallery</a>

Run SSG immediately after page loads is useful, when the html page is just a plain list of links without any design. There is nothing much to see without SSG. So the gallery can run in the no e×it mode - no close icon, no ESC key.

<body onload='{noExit:true})'>

Sample gallery with no e×it mode

Use initImgId parameter to set the initial image in the gallery. SSG auto­mati­cally numbers image hyperlinks on the page, the first photo has ID 0.

<button onclick=" {initImgID: 6} )"> Click me </button>

With the cfg parameter you can override global configuration, it applies only for the actual gallery run. The cfg parameter is an object which have the same parameters as the global configuration.

<a onclick=" cfg: { scrollDuration: 1333, theme:'black', fileToLoad = 'speciallinks.html' } )"> Click me </a>

You can pass into SSG an array of images and captions to show them in the gallery via imgs parameter. If you also add imgsPos parameter, images can be combined with photos from the page. The imgsPos:'start' places imgs before photos from the page, imgsPos:'end' after them. The imgsPos:'whole' shows in the gallery just imgs. It is a default parameter, which is no need to use. If you don't define imgs parameter, imgsPos will be ignored. {imgs: [ { href: 'img URL', alt: 'img caption, author: 'photo by…' }, {...} ], imgsPos:'start'} );

SSG.restart() method

Restart method ends the running SSG gallery and then calls with new parameters. It has the same parameters as the method. On this page the restart method is used in singpost after the gallery. It runs another gallery without exit fullscreen mode or reloading a page.

Examples of initiating the gallery by method

Run the gallery by Javascript calling:

The first picture in this gallery will be the picture with ID 0 (unless it doesn't have nossg class ). without para­meters shows photos from all galleries on the page.

Run the gallery by Javascript calling:{ initImgID: 12, fs:true })

The first photo will be the photo with ID 12, even if it has gossg class. The initImgID parameter respects .ssg classes and shows only pictures from galleries related to initImgID picture. Also the gallery theme is taken from css class of related gallery. The fs:true activates full screen mode.

Run the gallery by Javascript calling: { imgs: [ { href: 'traelanipa.jpg', alt: 'Trælanípa (Slave) Cliff' } ], imgsPos:'start', initImgID: 11 });

The imgsPos parameter tells the gallery to put traelanipa.jpg before the gallery which contains image with ID 11.

Run the gallery by Javascript calling: { imgs: iceland, fs:true, initImgID: 1 }); -------- iceland = []; iceland[ 0 ] = { href: 'img/reynisdrangar-black-beach.jpg', alt: 'Black beach Reynisfjara, Reynisdrangar rocks' }; iceland[ 1 ] = { href: 'img/Seljalandsfoss.jpg', alt: 'Aurora behind Seljalandsfoss waterfall', author: 'photo by Flor' }; iceland[ 2 ] = { href: 'img/iceland-horses.jpg' };

Without the imgsPos parameter, in the gallery will be only photos from array iceland. The initImgID works even with arrays.

Run the gallery by Javascript calling: { imgs: iceland, cfg: { scrollDuration: 1333, watermarkText = '🌋 Iceland', theme:'black', fileToLoad = 'bloglinks.html' }} )

The gallery with local settings. It has slower transition between photos, black color and different watermark and signpost.

SSG as a Javascript module

Story Show Gallery can also work as a Javascript module. Just add into ssg.js file this line to export SSG object:

export default SSG;

Themes: Dim Dark Black Light

Gallery with text links

Story Show Gallery also supports text hyper­links. All four follow­ing pict­ures will appear in separate gallery (because of .ssg class):

🐰 Massive pink rabbit man‑eater - a text link to a photo.
Enlightment inside Bankang cave
🔗 A broken link - You will notice it before site visitors do
an empty (invisible) link to the picture with SSG logo.

  1. SSG features, sample gallery
  2. License
  3. Implementation + configuration
  4. Complete configuration ⧉
  5. SSG files and minifying
  6. Controling SSG by CSS classes
  7. Gallery events
  8. Order of photos in the gallery
  9. Deep linking, scrolling
  10. & SSG.restart method
  11. examples
  12. SSG as a Javascript module
  13. 🎨 Visual themes
SSG logo

SSG configuration as it is at the begining of ssg.js file: ×

// duration of scroll animation in miliseconds. Set to 0 for no scroll animation. SSG.cfg.scrollDuration = 500; // Force SSG to always display in fullscreen - true/false SSG.cfg.alwaysFullscreen = false; // Force SSG to never display in fullscreen - true/false There is an exception for smartphones and tablets SSG.cfg.neverFullscreen = false; // Visual theme of the gallery - four possible values: dim, light, black, dark (default) SSG.cfg.theme = 'dark' // URL of the HTML file to load behind the gallery (usually a signpost to other galleries). // HTML file has to be loaded over http(s) due to a browser's CORS policy. Set to null if you don't want it. SSG.cfg.fileToLoad = null; // display social share icon and menu SSG.cfg.socialShare = true; // log image views into Google Analytics - true/false. SSG supports only ga.js tracking code. SSG.cfg.logIntoGA = true; // Protect photos from being copied via right click menu - true/false SSG.cfg.rightClickProtection = true; // Side caption for smaller, landscape oriented photos, where is enough space below them as well as on their side. true/false SSG.cfg.sideCaptionforSmallerLandscapeImg = false; // false means caption below // in other cases caption position depends on photo size vs. screen size. // Locking the scale of mobile viewport at 1. Set it to true if the gallery has scaling problem on your website. SSG.cfg.scaleLock1 = false; // Show first 3 images of a separate gallery together - e.g. third image clicked - image order will be 3,1,2,4,5,6... SSG.cfg.showFirst3ImgsTogether = true; // Watermark - logo configuration. Enter watermark text or image URL to display it SSG.cfg.watermarkWidth = 147; // image watermark width in pixels, it is downsized on smaller screens. SSG.cfg.watermarkImage = ''; // watermark image URL e.g. '' SSG.cfg.watermarkText = ''; // watermark text, use <br> tag for word wrap SSG.cfg.watermarkFontSize = 20; // font size in pixels SSG.cfg.watermarkOffsetX = 1.8; // watermark horizontal offset from left in percents of photo SSG.cfg.watermarkOffsetY = 1.2; // watermark vertical offset from bottom in percents of photo SSG.cfg.watermarkOpacity = 0.36; // opacity // Here you can translate SSG into other language. Leave tags <> and "" as they are. SSG.cfg.hint1 = "Browse through Story Show Gallery by:"; SSG.cfg.hint2 = "a mouse wheel <strong>⊚</strong> or arrow keys <strong>↓→↑←</strong>"; SSG.cfg.hint3 = "or <strong>TAP</strong> on the bottom (top) of the screen"; SSG.cfg.hintTouch = "<strong>TAP</strong> on the bottom (top) of the screen<br> to browse through Story Show Gallery."; SSG.cfg.hintFS = "For a better experience <br><a>click for fullscreen mode</a>" SSG.cfg.toTheTop = "Scroll to top"; SSG.cfg.exitLink = "Exit the Gallery"; // share link dialog SSG.cfg.imageLink = "The link to selected image:"; SSG.cfg.copyButton = "⎘ Copy the link to clipboard"; SSG.cfg.linkPaste = "…and you can paste it anywhere via ctrl+v"; // in the portrait mode the gallery suggest to turn phone into landscape mode SSG.cfg.showLandscapeHint = true; SSG.cfg.landscapeHint = 'photos look better in landscape mode <span>😉</span>'; // SSG events - see complete example of SSG events in the example directory SSG.cfg.onGalleryStart = null; // fires after creating a gallery SSG.cfg.onImgChange = null; // fires on every image change (even the first one) SSG.cfg.onSignpost = null; // fires when a user reach HTML signpost after photos or if he scrolls after the final menu SSG.cfg.onGalleryExit = null; // fires on the gallery exit