No description, website, or topics provided.
Switch branches/tags
Nothing to show
Clone or download
Darick Carpenter
Latest commit cd3571c Oct 18, 2018

Module: Background Slideshow

Show a slideshow of images in the background. Great for a photo frame from instead of a mirror.

The MMM-BackgroundSlideshow module is designed to display images fullscreen, one at a time on a fixed interval, from one or many directories. These images can be shown in order or at random, one directory at a time or all at time. The images can transition from one to the other and be shown with no edge (cover) or the enter image(contain).

Based on MMM-ImageSlideshow.

Dependencies / Requirements

This module requires no special dependencies. The only requirement is that the image directories you path to are fixed paths accessible to the Magic Mirror instance.


This module will take in a list of directory paths, one or more, containing image files. The module will display those images in either alphabetical or random order, across either each path one at time or across all the paths at once. Once all the images have been shown, it will loop back and start again.

Extra configurations include setting the amount of time an image is shown for, selecting which file extensions are valid, the transition speed from one image to another, the background sizing, whether or not to animate the transition from one to the other, the gradient used to make the text more readable, and the gradient opacity.

Using the module

Use Git to download. Make sure Git is installed on your system. In the command line/terminal, go to the modules directory of the your Magic Mirror install. run: 'git clone'. The advantage of using Git is when there is an update, you can run 'git pull' and it will pull down all the updates. Magic Mirror can even let you know when there are updates.


Download the zip file Unzip contents into the modules directory of your Magic Mirror install. Rename the 'MMM-BackgroundSlideshow-master' folder to 'MMM-BackgroundSlideshow'.

Add the module to the modules array in the config/config.js file:

modules: [
    module: 'MMM-BackgroundSlideshow',
    position: 'fullscreen_below',
    config: {
      imagePaths: ['modules/MMM-BackgroundSlideshow/example1'],
      transitionImages: true,
      randomizeImageOrder: true

I also recommend adding the following to the custom.css to make the text a little brighter:

body {
    color: #fff;

Configuration options

The following properties can be configured:

Option Description
imagePaths Array value containing strings. Each string should be a path to a directory where image files can be found.

Example: ['modules/MMM-ImageSlideshow/example1']
This value is REQUIRED
slideshowSpeed Integer value, the length of time to show one image before switching to the next, in milliseconds.

Example: 6000 for 6 seconds
Default value: 10000 or 10 seconds
This value is OPTIONAL
randomizeImageOrder Boolean value, if true will randomize the order of the images, if false will use an alphabetical sorting by filename.

Example: true
Default value: false
This value is OPTIONAL
recursiveSubDirectories Boolean value, if true it will scan all sub-directories in the imagePaths.

Example: true
Default value: false
This value is OPTIONAL
validImageFileExtensions String value, a list of image file extensions, seperated by commas, that should be included. Files found without one of the extensions will be ignored.

Example: 'png,jpg'
Default value: 'bmp,jpg,gif,png'
This value is OPTIONAL
transitionSpeed Transition speed from one image to the other, transitionImages must be true. Must be a valid css transition duration.

Example: '2s'
Default value: '1s'
This value is OPTIONAL
backgroundSize The sizing of the background image. Values can be:
cover: Resize the background image to cover the entire container, even if it has to stretch the image or cut a little bit off one of the edges.
contain: Resize the background image to make sure the image is fully visible

Example: 'contain'
Default value: 'cover'
This value is OPTIONAL
transitionImages Transition from one image to the other (may be a bit choppy on slower devices, or if the images are too big).

Example: true
Default value: false
This value is OPTIONAL
gradient The gradient to make the text more visible. Enter gradient stops as an array.

Example: [ "rgba(0, 0, 0, 0.75) 0%", "rgba(0, 0, 0, 0) 40%" ]
Default value: [ "rgba(0, 0, 0, 0.75) 0%", "rgba(0, 0, 0, 0) 40%", "rgba(0, 0, 0, 0) 80%", "rgba(0, 0, 0, 0.75) 100%" ]
This value is OPTIONAL
gradientDirection The direction of the gradient

Example: 'horizontal'
Default value: 'vertical'
This value is OPTIONAL