snowfall-js-plugin
Advanced tools
Snowfall-js-plugin is a JavaScript library to add some winter magic to your project. This package creates animated snowflakes on a web page using HTML5 canvas and JavaScript classes, no dependencies. You can customize the number, size, speed, color and te
Snowfall-js-plugin is a JavaScript library to add some winter magic to your project. This package creates animated snowflakes on a web page using HTML5 canvas and JavaScript classes, no dependencies. You can customize the number, size, speed, color and text of the snowflakes, and enjoy the beautiful snow falling effect on your website or app. Snowfall.js-plugin is easy to use and compatible with most browsers and devices.
The plugins comes with optional features:
To use the Snowfall-js-plugin, you need to install the NPM package:
npm install snowfall-js-plugin
Note: If you only want the snowfall.js file without the bells and whistles that this plugin package provides, download the file snowfall.js from the original snowfall.js repo and include it in your project manually.
After you've installed the plugin package, import the plugin into your project's app.js or vendor.js file.
import { snowAnimationStart } from "snowfall-js-plugin";
document.addEventListener("DOMContentLoaded", function () {
snowAnimationStart();
});
This will run the plugin with the default configuration. See Configuration Options for more information.
The package comes with a static demo page whereby you can experiment with the various configuration options for the snowfall animation and the custom on/off toggle switches. After you've installed the package run this command:
npx snowfall-js-demo
This will spin up a http-server on localhost port 8080 and serve the demo page.
Note: you may be prompted to install http-server as a dev dependency. Once installed, click on the output link in the terminal to open the demo in your browser (localhost:8080/demo). If you see a directory list, click on the demo folder.
The demo runs with logLevel: "info", so you can check the console for informative messages about what is going on in the background.
The page that is served contains a form with all most of the configuration options. Experiment until you you've found your preferred configuration options. Next, proceed to defining a custom configuration object.
Below you find the default configuration object. Most of the settings are self-explanatory but continue reading below for a more detailed explanation.
const defaultParams = {
logLevel: "default", // default or info
checkHardware: true,
checkDateRange: true,
dateRange: {
startMonth: 12, // 1-12
endMonth: 2, // 1-12
startDay: 15, // 1-31
endDay: 15, // 1-31
},
autostartOnMobile: true,
autostartOnDesktop: true,
screenWidthThreshold: 768, // pixel value, use a number without px
checkReducedMotionPreference: true,
setReducedMotion: "disable", // "disable" or "reduce"
reduceMultiplier: 0.5,
// experimental: reduces snowfall count by 50%, use a value between 0.1-0.9
snowfall: {
count: 33, // number of snowflakes
minRadius: 10, // min size of snowflakes
maxRadius: 30, // max size of snowflakes
minSpeed: 3, // min fall speed of snowflakes
maxSpeed: 6, // max fall speed of snowflakes
text: "\u2744", // symbol or text of the snowflakes
color: "#99ccff", // color of the snowflakes
zIndex: "1000", // adjust according to project stacking context
canvasHeightLimit: 0, // 0 = no limit; 1 = 100vh, 2 = 200vh
},
switches: {
show: true,
storeUserSettings: true,
txt: "Snow",
txtElemAttributes: [],
injectCSS: true,
styles: {
/* background color of the switch when turned off */
bgClrOff: "rgba(189, 195, 199, 1)", // #bdc3c7
/* background color of the switch when turned on */
bgClrOn: "rgba(149, 165, 166, 1)", // #95a5a6
/* color of the moving toggle inside switch */
toggleClr: "#ffffff",
/* color and position of the text next to the switch */
txtClr: "rgba(33, 37, 41, 1)", // #212529
txtPosition: "2", // "1" = left of switch or "2" = right of switch
},
},
};
Checking hardware via the browser is unreliable but a hardware check is on by default to stop the animation from running on low end devices. This is useful when your website has lots of other computationally heavy JavaScript or other animations like scroll animation that are more important than fancy snowflakes. Thus, on low end devices this code will not run and no switches will be appended to the DOM.
The hardware check relies on the browser Navigator API to check hardware concurrency or device memory. One of the trade-offs to be aware of is that if the browser does not report hardware info or provides inaccurate estimates, the animation will not be loaded.
You can disable this check by setting the option: checkHardware: false in the configuration object.
By default the animation is set to be loaded between December 15 and February 15 on any given year. You can set it and forget it. Outside of this date range, the animation code will not be loaded and no switches will be present in the DOM.
You can set your own date range by changing the following options:
{
dateRange: {
startMonth: 12, // 1-12
endMonth: 2, // 1-12
startDay: 15, // 1 - days in the month
endDay: 15, // 1- days in the month
},
}
The date range is validated so you will get an error when, for example, startDay > endDay while startMonth is the same as the endMonth. The animation will run on February 29 in a leap year but you cannot set the start or end date to be February 29.
If you want the code to be loaded all year set checkDateRange: false.
Most options are self-explanatory. For example, "count" is the number of snowflakes that are rendered on the canvas at any given time. There is no minimum or maximum but take into account that the browser will have to perform calculations on each snowflake. The calculations and canvas drawings are batched together but you will notice performance issues if you set your value too high. The recommended maximum is 100.
The minRadius and maxRadius determine the size of the snowflakes. By default you get a nice mixture of small and large snowflakes but adjust to your own taste.
The minSpeed and maxSpeed values determine how fast the snowflakes dwindle down. This is related to the snowflake size. Bigger flakes will fall faster than smaller ones. Take into account that some people may experience discomfort with fast moving objects. The recommended maxSpeed value is 6.
The snowflakes are drawn on the screen via an HTML Canvas element. By default the height of the canvas will take up the entire scrollable area. This is nice because the snowflakes will dwindle all the way to your footer area. However, on pages with lots of content the performance will become problematic. You'll have to test this yourself but if your page is over 8000px long, you may want to start limiting the height of the canvas.
{
snowfall: {
canvasHeightLimit: 1, // 0 = no limit; 1 = 100vh; 2 = 200vh; 3 = 300vh; etc.
}
}
By default, the animation will start automatically. That is, if it passes the hardware check and the current date falls within the specified date range.
You can also leave the decision to run the animation up to the user. If you choose to do so, make sure you have one or more switches available on your site (see switches). The user then needs to manually turn the animation on.
The configuration offers two settings: autoStartOnMobile and autoStartOnDesktop. Both are set to true by default. This setting is based on the window.innerWidth >= screenWidthThreshold condition. The default value to differentiate between small and large screens is set to 768 pixels.
There should be no performance issues on mid-range to high-end mobile devices nor on desktop.However, if your website already contains lots of scroll animations or other JavaScript code that requires lots of calculations, you may want to consider disabling autoStart for mobile devices. The hardware check mentioned above will already filter out low-end devices but hardware checks via the browser are not always reliable. The autostart settings provide you with an extra option.
The switches are keyboard focusable and can be turned on and off by pressing the Enter key.
Some users can experience discomfort with lots of moving animations on a screen, see MDN, Prefers Reduced Motion. When this type of browser setting is detected the plugin offers two options for you to configure: disable the animation entirely or reduce the number of moving snowflakes by a percentage of your choice. The plugin will check the browser settings via the method window.mediaMatch('prefers-reduced-motion') and apply the setting of your choice (disable or reduce). The default option is to disable the animation.
{
setReducedMotion: "reduce", // default = "disable"
reduceMultiplier: 0.5,
// experimental: reduces snowfall count by 50%, use a value between 0.1-0.9
}
If accessibility is of no concern, you can turn this behavior off by setting the configuration object to: checkReducedMotionPreference: false.
By default the plugin will look for container elements with class="snow-animation-switch" and append the custom switch elements as children to the container. If no container elements are found, a warning will be shown in the console (only on logLevel = "info").
If you want to use the switch functionality simply add one or more container <div class="snow-animation-switch"></div elements to your HTML page, for example, one in your header menu or navigation bar and one in your footer area. The behavior of these switches is synchronized, thus if you toggle the animation on/off on one switch, the state of the other switches will be updated automatically. You can add as many switches as you like.
The label text that accompanies the switch can be set in the configuration options object, as well as its position: left-side or right-side of the switch.
You can also configure the styles (colors) that will be applied to the different element components of each switch.
The switches are responsive to font-size so you can make then bigger or smaller by playing around with font-size on the parent element.
By default this plugin will append a minified CSS file to the DOM (snowAnimationSwitchStyles.css).
Note about build tools: If your website project uses a build tool like ParcelJs the additional stylesheet will be picked up automatically. You don't need to do extra work. However, if you rely on a more custom build setup with Gulp, Grunt and/or Webpack you might have to do some extra configuration work in your build tools — especially in production, to make sure that the minified css stylesheet is included.
You also have the option to add these styles (or your own) manually to your project's (S)CSS. If that is the case set the option injectCSS: false in the custom configuration object.
Below you find the CSS that is included in the snowfall-js-plugin stylesheet.
/* The switch has various components:
- The label text next to the switch can appear either left-side or right-side using flexbox order property.
- The checkbox element itself is made invisible and only used for its functionality.
- The label element is the element that is actually visible to the user.
- The switch is able to scale with the font-size.
- You may have to adjust the line-height to get the desired vertical alignment
- Based on https://codepen.io/jorishr/pen/xxxPPLP
*/
:root {
--snow-animation-switch-bgClrOff: rgba(189, 195, 199, 1);
--snow-animation-switch-bgClrOn: rgba(149, 165, 166, 1);
--snow-animation-switch-toggleClr: #fff;
--snow-animation-switch-txtClr: rgba(33, 37, 41, 1);
--snow-animation-switch-txtPosition: 2;
--snow-animation-switch-txtMargin: 0 0 0 0.75em;
}
.snow-animation-switch {
display: none;
}
.snow-animation-switch--show {
display: flex;
justify-content: center;
}
.snow-animation-switch__input {
height: 0;
width: 0;
visibility: hidden;
}
.snow-animation-switch__label {
position: relative;
display: block;
text-indent: -9999px;
cursor: pointer;
width: 2.5em; /* 40px */
height: 1.25em; /* 20px */
background: var(--snow-animation-switch-bgClrOff);
border-radius: 1.25em; /* 20px, equal to height */
order: 2;
}
.snow-animation-switch__label::after {
content: "";
position: absolute;
top: 0.125em; /* 2px */
left: 0.125em; /* 2px */
width: 1em; /* 16px */
height: 1em; /* 16px */
background: var(--snow-animation-switch-toggleClr);
border-radius: 1em; /* 16px */
transition: 0.3s;
}
/* extend the toggle when active */
.snow-animation-switch__label:active::after {
width: 1.375em; /* 22px */
}
.snow-animation-switch__input:checked + label {
background: var(--snow-animation-switch-bgClrOn);
}
.snow-animation-switch__input:checked + label::after {
left: calc(100% - 0.125em); /* 100% - 2px */
transform: translateX(-100%);
}
.snow-animation-switch__text {
line-height: 1.25;
order: var(--snow-animation-switch-txtPosition);
color: var(--snow-animation-switch-txtClr);
margin: var(--snow-animation-switch-txtMargin);
}
Take a look at the file switch.js to see how and where this CSS file is appended to the DOM.
If you want more control over the label text that accompanies the switches, you can add element attributes. For example:
{
txtElemAttributes: [
{ type: "attribute", name: "id", value: "snow-switch-text" },
{ type: "data-attribute", name: "txt_id", value: "33" },
];
// -> <span id="snow-switch-text" data-txt_id="33"></span>
}
Note the distinction between regular element attributes and data-attributes. The latter is set via the dataset property of the element.
If you only want the snow animation without the ability for the users to turn the animation on or off, you can set the option:
{
switches: {
show: false,
}
}
By default, the user's preference to enable or disable the animation is stored in local storage under the key-value pair: "userSettings": {runSnowfallAnimation: true/false}. If you don't want this, you can disable this feature:
{
switches: {
storeUserSettings: false,
}
}
The default log level will only log errors to the browser console. During development you can set logLevel: "info" to get more informative messages and warnings in the browser console.
You can pass a customized configuration object to the snowAnimationStart() function. For example:
import { snowAnimationStart } from "snowfall-js-plugin";
const customConfig = {
logLevel: "info", // "default" or "info"
checkHardware: false,
snowfall: {
count: 33,
color: "#ffffff",
},
switches: {
storeUserSettings: false,
txt: "Snow",
},
};
document.addEventListener("DOMContentLoaded", function () {
snowAnimationStart(customConfig);
});
The parameters you pass via the object will be validated first and the values from the default configuration will be used as a fallback. Check for warnings or errors in your browser developer console. It is recommended to copy and paste the default configuration object and modify the settings according to your needs.
This README should contain all the information you need to configure and integrate the plugin into your website application. If you want to dig deeper, you can consult the JSDoc documentation. Most JavaScript files have JSDoc style comments for every function. You can find the JSDoc documentation in the docs folder of the project, or you can conveniently run the following command: npx snowfall-js-docs which will spin up a http-server and serve the JSDoc documentation HTML files in your browser.
If you find bug or issues related to this project, please open an issue in the GitHub repository: snowfall-js-plugin
This project is distributed under the GNU GPL v3.0 license. You can freely use, modify and distribute this code, but you must keep the authorship of the original code and indicate the license. You must also share your changes under the same license. You can read more about the license in the file LICENSE.
FAQs
Snowfall-js-plugin is a JavaScript library to add some winter magic to your project. This package creates animated snowflakes on a web page using HTML5 canvas and JavaScript classes, no dependencies. You can customize the number, size, speed, color and te
The npm package snowfall-js-plugin receives a total of 15 weekly downloads. As such, snowfall-js-plugin popularity was classified as not popular.
We found that snowfall-js-plugin demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.