How to create widgets that work anywhere on the web

I get many clients that want me to simply build a small widget/pricing table/calculator for their website. The beauty of widgets is that they are completely independent of the platform they are running on. My client could be using WordPress, Wix, Drupal, Django or any back-end/front-end framework for that matter and all I have to do is deliver a small HTML file which will contain the CSS and JavaScript necessary for it to function.

But that’s where things get interesting. The tricky part is to write CSS and JavaScript such that it doesn’t conflict with or override any of the functionality of the client’s website. The ideal deliverable would be a simple piece of code that the client can simply copy-paste into his/her site and it should just work.

Here is my recommended way of implementing widgets.

First, the HTML. Ideally the markup of your widget should be in a container which is given a unique (unique-enough?) ID so that it doesn’t conflict with any other DOM element on the page. I personally prefer to simply create a div with the id of #calc

<div id="calc">

Now all the markup for your widget will be inside this container. And if you use Pug like I do then this gets reduced to


Now for the CSS. Another benefit of giving our main container an ID is that all the CSS that we write will be prefixed by that ID so that it only affects the elements that are inside the div. For example, if I have two input elements with class form-input

input(class='form-input' type='text' name='firstname')
input(class='form-input' type='text' name='lastname')

then my CSS to style these inputs would be something like this

#calc .form-input {
// height, width and whatever

This approach is fine, but I much more prefer to use SCSS and then nest the CSS rules.

#calc {
.form-input {
// color, background and other stuff

That way I can simply add more classes and rules under the #calc tag and SCSS will automatically compile them to CSS

Next we have JavaScript. Now, JavaScript has some issues with the scoping of variables and we need to get around those and completely encapsulate our code so that it doesn’t interfere with other code on the site. I like to do this by using an Immediately Invoked Function Expression or IIFE for short.

This is what it looks like in JavaScript

(function() {
// code that does stuff

Notice the () at the end after the } . This basically calls the function and all of the above code immediately after defining the function. Any variables or functions that are defined within the IIFE will only be accessible inside it and will be completely hidden from anywhere outside the function. This ensures that my code is safe and secure.

Bringing it all together

Now all of the above looks like a hassle to setup in each project so to help with that I created a small starter kit to help anyone who is interested. I personally use Pug, SCSS and ES6 to write my widgets and so I wrote a Gulp.js config that lets me use those while writing my code and simply transpiles it all to pure HTML, CSS and JavaScript. Here take a look.

Simply create the widget of your choice and after running Gulp, you will get a simple HTML file will the CSS and JavaScript embedded into it.