Google Chrome extensions are applications that run in the Chrome browser. They provide additional features, integration with third-party websites or services, and customized browsing experiences.
In this step-by-step tutorial, I’ll show you how to code a Google Chrome extension from scratch with the basic web technologies: HTML, CSS, and JavaScript.
We’ll build a simple language picker extension, and in the process of building this, we’ll learn about some new and exciting ways to code in JavaScript.
By the end of this tutorial, you should know how to build your own Chrome web extension from scratch.
1. Chrome Developer Mode Setup
Before we start building the extension, we’ll need to turn on Developer mode in our Chrome browser. This feature allows developers to actively test, debug, and preview the extension while it’s still in development.
To enable developer mode, click on the three dots on the top right of your window, go to More Tools > Extensions, and then toggle on Developer mode at the top right.
Now you’ll be able to load and test your extension in your browser.
Also, you can check out the Chrome API reference to learn about the various APIs made available by Chrome for building extensions. We’ll be using a couple of these APIs later on in the tutorial.
2. Creating the Manifest File
The manifest file gives Chrome all the information it needs about your extension.
Before creating a manifest file, create an empty folder for your project—I’ll refer to it henceforth as project folder. I named mine Lpicker.
Inside the folder, create the file manifest.json and include the following code in it:
"name": "Language Picker", "description": "A simple extension for choosing from different language options", "version": "1.0", "manifest_version": 3, "background": "service_worker": "background.js" , "permissions": ["storage"]
The name, description, and version attribute all provide the information that will be displayed publicly on our extension when it is loaded to the browser.
The manifest_version
property is especially important to Chrome. Chrome has three manifest versions: 1, 2, and 3. Version 1 is deprecated, and version 3 is the latest and recommended version at the time of writing.
The permissions
property is an array of APIs that we want Chrome to grant our extension access to.
background
contains the service worker. service_worker
points to the JavaScript code that will be run whenever our extension is loaded onto the browser.
We are going to create the background code, but before doing that, we need to create our language flags.
3. Adding Flag Icons
Create the flags directory in your project folder, and then download five flag images representing five different languages. You can download the flag icons from flaticon.
Make sure you use the following naming convention when saving each flag: english.png, chinese.png, italian.png, etc. as shown below.
Now create the service worker file background.js and include the following code in it:
let language="url(flags/english.png)"; chrome.runtime.onInstalled.addListener(() => chrome.storage.sync.set( language ); console.log(`Default background language set to $language`); )
In the code, we simply add an event listener to listen for the running of our extension. When our extension is about to run, we access the local storage API on Chrome and set English as the default language, represented by the flag URL.
Now navigate your browser to chrome://extensions/, click on the Load unpacked option, navigate to your project folder, and select it. If your web manifest is correct, then Chrome will load your extension successfully.
You should find that your extension looks something like this:
4. Creating the Popup Menu
Whenever we click on our extension icon on the taskbar, we want a small popup containing our language options (represented by the flags) to appear.
We begin by adding an actions
key just above background
inside our manifest.json file:
"action": "default_popup": "popup.html" ,
If you’re using manifest version 2, it is going to be browser_action
and not action
.
Now that we have created a reference to the popup page, let’s create the markup for displaying it.
Create the file popup.html inside your project folder and include the following markup:
<!DOCTYPE html> <html lang="en"> <head> <link rel="stylesheet" href="https://code.tutsplus.com/tutorials/popup.css"> </head> <body> <div class="container"> <button id="activeFlag"></button> </div> <script src="popup.js"></script> </body> </html>
First, we include a link to popup.css. Here’s the content of the stylesheet:
.container width: 300px; button height: 30px; width: 30px; outline: none; border: none; border-radius: 50%; margin: 10px; background-repeat: no-repeat; background-position: center; background-size: contain;
In the HTML body, we create a container <div>
element to hold our flag, which is represented by a button element.
Towards the end of the HTML, we also link a script named popup.js. Now create popup.js inside your folder and use the following code:
const activeFlag = document.getElementById('activeFlag'); chrome.storage.sync.get("language", ( language ) => activeFlag.style.backgroundImage = language; );
For now, this script is responsible for retrieving the default flag’s URL from local storage and passing it as a background image to the button. We’ll augment the code later on.
Reload the extension in your browser and pin it to your taskbar for quick access.
When you click on your extension on the taskbar, a popup containing the English flag should show in your browser.
5. Adding an Icon
To add an icon to our extension, we’ll do two things. First, we’ll modify our manifest.json file by adding a default_icon
field inside actions:
"action": "default_popup": "popup.html", "default_icon": "16": "./images/uk.png", "32": "./images/uk.png", "48": "./images/uk.png", "128": "./images/uk.png" ,
Here, we specify an icon for the different pixel sizes. To make things easy, I used the same image for the various pixel sizes, but you should always use different sizes of the image.
Then, just under the actions
field in the manifest, we need to also add an icons
field containing the same values and icon paths:
"icons": "16": "./images/uk.png", "32": "./images/uk.png", "48": "./images/uk.png", "128": "./images/uk.png" ,
Save your file and refresh your extension at chrome://extensions/ on the browser. Your new icon should reflect in the extension, as below.
6. Adding Other Language Options
We’ll now include the other language options in our popup menu.
We’ll begin by updating the container <div>
inside popup.html. This element will act as a wrapper for the other flags we are going to create. Update the container
div with the following code:
<div class="container"> <button id="activeFlag"></button> <div id="flagOptions"> <p>Choose a different language</p> </div> </div>
Then, adding to our popup.js file, we’ll create a reference to div.flagOptions
, and create an array containing the language options:
const flagOptions = document.getElementById("flagOptions"); const otherLangs = ["english", "chinese", "hindi", "italian", "german"];
Below, we’ll create the function constructFlags
. As its name suggests, this function will be responsible for creating and inserting the other flags into div.flagOptions
in the popup menu:
function constructFlags(otherLangs) chrome.storage.sync.get("language", (data) => const currentLang = data.language; for (let lang of otherLangs) const button = document.createElement("button"); const langURL = `url("flags/$lang.png")` button.dataset.language = langURL; button.style.backgroundImage = langURL; if(lang === currentLang) button.classList.add(".currentFlag"); button.addEventListener("click", handleFlagClick) flagOptions.appendChild(button); )
constructFlags
takes the array of languages (which are incidentally also file prefixes) as an argument and accesses the active language from the local storage.
Then, in a for
loop, we construct a new button and set the current flag as the background image of the new button. If the currently iterated language option matches the active language option in local storage, we then add the .currentFlag
class to the button.
We then listen for a click event on the button and call handleFlagClick
whenever that event is triggered. Finally, we append the button to the container <div>
in the popup menu.
Here’s the logic for the function handleFlagClick
:
function handleFlagClick(e) const currentFlag = e.target.parentElement.querySelector('.currentFlag'); if(currentFlag && currentFlag !== e.target) currentFlag.classList.remove(".currentFlag") const language = e.target.dataset.language e.target.classList.add(".currentFlag"); chrome.storage.sync.set( language ); activeFlag.style.backgroundImage = language;
This function basically removes the .currentFlag
class from the other language options and then adds the class to the option clicked by the user.
Finally, still in popup.js, we call the constructFlags()
function with the list of languages:
constructFlags(otherLangs);
That’s all for the coding of this extension! You can grab the source code for this project from our GitHub repository.
7. Publishing Your Extension
The last step is to publish your extension. To do so, you’ll need to first register as a Chrome Web Store developer. The process is very straightforward, although you’ll be required to pay a small fee ($5 at the time of writing).
After payment, you’ll be allowed to log in to the developer console with your Google account. From there, you’ll be prompted to upload your new extension and publish it to the Chrome Web Store.
Once your submission is approved, your extension will appear in the Chrome Web Store and can subsequently be installed by any Google Chrome user.
Wrapping Up
And that’s it! I hope this tutorial taught you something new and useful.
In this step-by-step guide, we built a simple language picker extension using just HTML, CSS, and JavaScript code.
You should now be able to work with different Chrome browser APIs to build your own extensions from scratch with just basic web code!
Icons made by FreePik from www.flaticon.com.