Sebastian Gomez

Jun 24, 2026

Updated: Jun 25, 2026

The Manifest and Its Properties

Introduction

In this post I'll guide you through the steps needed to develop your own Chrome extension using version 3 of the manifest (Manifest V3). From creating the manifest file to configuring icons and other essential details, we'll cover everything you need to know to get started.

First steps: creating the manifest file

The manifest file is fundamental to any Chrome extension. It provides the browser with crucial information about the extension, such as its main files and the capabilities it will use. With each new version of the manifest, the features of the extensions platform change. In this post we'll work with Manifest V3, and we'll begin by creating a JSON file for our extension.

Note: Manifest V3 is the current and required version in 2026. Manifest V2 has reached end of support, so every new extension must use "manifest_version": 3.

Basic structure of the manifest file. Create a file called manifest.json. This file must contain a JSON object with the following structure:

{
  "manifest_version": 3,
  "name": "Mi Extensión",
  "version": "0.0.1",
  "description": "Descripción de mi extensión"
}

Loading the extension in Chrome

Once the manifest file is created, the next step is to load the extension in Chrome.

1. Enable Developer Mode. Open Chrome and navigate to chrome://extensions/. Turn on "Developer Mode" in the top right corner.
2. Load the extension. Click "Load unpacked" and select the folder that contains your manifest.json file.

You'll see your extension listed. Any change you make to the manifest can be applied by reloading the extension.

Adding icons to the extension

Extensions usually include icons to improve the user experience. Manifest V3 lets you specify different icon sizes for different parts of the browser.

Define the icons in the manifest. Add an icons section to your manifest.json:

{
  "manifest_version": 3,
  "name": "Mi Extensión",
  "version": "0.0.1",
  "description": "Descripción de mi extensión",
  "icons": {
    "16": "icon-16.png",
    "48": "icon-48.png",
    "128": "icon-128.png"
  }
}

Prepare the icon files. Create icons in the specified sizes (16x16, 48x48, 128x128) and place them in your project folder.

Update and reload. After updating the manifest with the icons, reload the extension to see the changes applied.

Configuring the extension action

The chrome.action API in Google Chrome Extensions Manifest V3 lets you control the extension icon that appears in the browser toolbar. This API is fundamental for managing how the extension is presented and behaves in the user interface. By including the action key in the extension's manifest.json file, you can define elements such as the default icon, the title shown when hovering over the icon, and a popup that appears when the user clicks the icon. This improves the extension's interactivity and usability, letting developers provide extra information or specific features directly from the browser toolbar.

The API also lets you update these elements dynamically through several methods. For example, you can change the icon using chrome.action.setIcon(), set a title with chrome.action.setTitle(), and define or change the contents of a popup using chrome.action.setPopup(). In addition, you can manage the badges that appear over the icon to show status information, such as counters, using chrome.action.setBadgeText() and chrome.action.setBadgeBackgroundColor(). These methods let extensions adapt their appearance and behavior to the context, such as the contents of the current tab, improving the end user experience.

Add an action section. Update your manifest.json to include the action section:

{
  "manifest_version": 3,
  "name": "Mi Extensión",
  "version": "0.0.1",
  "description": "Descripción de mi extensión",
  "icons": {
    "16": "icon-16.png",
    "48": "icon-48.png",
    "128": "icon-128.png"
  },
  "action": {
    "default_icon": {
      "16": "icon-16.png",
      "48": "icon-48.png",
      "128": "icon-128.png"
    },
    "default_title": "Mi Asombrosa Extensión de Chrome"
  }
}

What is the difference between using icons and action.default_icon?

The main difference between using icons and action.default_icon in a Google Chrome extension lies in the purpose and usage context of each one:

icons:

• Purpose: defines the extension icons used in different contexts within the Chrome user interface, such as the Chrome Web Store page, the extensions manager, and the browser toolbar.
• Context: it's a global setting for the extension that specifies icons in different sizes so Chrome can use them wherever appropriate.

action.default_icon (inside the action key):

• Purpose: specifically controls the extension's action icon that appears in the browser toolbar. This is relevant for extensions that have direct interaction with the user through a toolbar button.
• Context: it's used to define the appearance of the action icon and its behavior (such as showing a popup on click) directly in the browser toolbar.

So, icons is used to define the extension's global icons in various sizes for different parts of the Chrome interface, while action.default_icon (inside the action key) is used specifically to control the icon and behavior of the extension's action button in the browser toolbar.

Reload and verify. Reload the extension and verify that the icons and the default title appear correctly in the toolbar.

Adding extra information

You can include more information in the manifest to personalize your extension even further.

Add the author's email. Add a line to your manifest.json to include the author's email:

{
  "manifest_version": 3,
  "name": "Mi Extensión",
  "version": "0.0.1",
  "description": "Descripción de mi extensión",
  "icons": {
    "16": "icon-16.png",
    "48": "icon-48.png",
    "128": "icon-128.png"
  },
  "action": {
    "default_icon": {
      "16": "icon-16.png",
      "48": "icon-48.png",
      "128": "icon-128.png"
    },
    "default_title": "Mi Asombrosa Extensión de Chrome"
  },
  "author": "miemail@example.com"
}

Set the default language. Specify the default language using default_locale:

{
  "manifest_version": 3,
  "name": "Mi Extensión",
  "version": "0.0.1",
  "description": "Descripción de mi extensión",
  "icons": {
    "16": "icon-16.png",
    "48": "icon-48.png",
    "128": "icon-128.png"
  },
  "action": {
    "default_icon": {
      "16": "icon-16.png",
      "48": "icon-48.png",
      "128": "icon-128.png"
    },
    "default_title": "Mi Asombrosa Extensión de Chrome"
  },
  "author": "miemail@example.com",
  "default_locale": "es"
}

When using localization in our extension, we need to create a directory structure that includes the corresponding localization files. Here are the steps to add localization to your Chrome extension.

Create the directory structure for localization. At the root of your project (that is, in public), create a folder called _locales. Inside this folder, create a subfolder for each language you want to support. In this case, we'll add support for Spanish (es).

my-chrome-extension/
├── _locales/
│   └── es/
│       └── messages.json
├── public/
│   ├── icon-16.png
│   ├── icon-48.png
│   └── icon-128.png
├── src/
├── manifest.json
└── package.json

Create the localization file. Inside the es folder, create a file called messages.json and add the contents of the localized messages. This file contains the Spanish messages that will be used in your extension.

{
  "appName": {
    "message": "Mi Extensión"
  },
  "appDescription": {
    "message": "Descripción de mi extensión"
  },
  "defaultTitle": {
    "message": "Mi Asombrosa Extensión de Chrome"
  }
}

Update the manifest.json file. Make sure the manifest.json uses the localized messages. Here's an updated example:

{
  "manifest_version": 3,
  "name": "__MSG_appName__",
  "version": "0.0.1",
  "description": "__MSG_appDescription__",
  "icons": {
    "16": "icon-16.png",
    "48": "icon-48.png",
    "128": "icon-128.png"
  },
  "action": {
    "default_icon": {
      "16": "icon-16.png",
      "48": "icon-48.png",
      "128": "icon-128.png"
    },
    "default_title": "__MSG_defaultTitle__"
  },
  "author": "miemail@example.com",
  "default_locale": "es"
}

This is how your extension should look:

Conclusion

Developing Chrome extensions may seem like a challenging task at first, but with a good understanding of the manifest and by following these steps, you can easily create your first extension. As you progress, you'll explore more features and capabilities to make your extension even more useful and appealing, such as localization or default icons. Good luck and let's get to work!

Suggested exercises

1. Create a minimal manifest.json with manifest_version, name, version, and description, and load it in chrome://extensions/ with Developer Mode enabled.
2. Add the three icon sizes (16x16, 48x48, 128x128) and an action key with its default_icon and default_title, reload the extension, and check that the icon appears in the toolbar.
3. Add localization support by creating _locales/es/messages.json and using the __MSG_*__ references in your manifest. Set default_locale as well.

3-point summary

1. The manifest.json is the heart of every Chrome extension and, in 2026, it must declare "manifest_version": 3.
2. The icons key defines the extension's global icons, while action.default_icon controls the toolbar button icon.
3. With default_locale and the _locales folder you can localize your extension using the __MSG_*__ references in the manifest.

That's all. I hope this post is useful to you and that you can apply it to a project you have in mind.

Leave me a comment if it helped, if you want to add an opinion, or if you have any questions. And remember, if you liked it, you can also share it using the social links below.