How to guide

<p>Building a Chrome extension might sound intimidating, but the truth is you can create a fully functional extension with just HTML, CSS, and vanilla JavaScript. No complex frameworks or build tools required. In this guide, we'll walk through creating a simple yet practical todo list extension that you can load directly into Chrome and use immediately.</p><p>Whether you're a beginner looking to level up your web development skills or an experienced developer wanting to extend Chrome's capabilities, this tutorial will show you exactly how to create a Chrome extension from scratch.</p><h2>What is a Chrome Extension?</h2><p>A Chrome extension is a small software program that extends Chrome's functionality by adding new features or modifying existing ones. Extensions are built using the same technologies as websites: HTML, CSS, and JavaScript. They can interact with web pages, modify their content, or provide standalone features accessible from your browser toolbar.</p><p>Chrome extensions are packaged in a specific structure with a manifest file that tells Chrome how to load and run your extension. Once loaded, you can access it from the Chrome toolbar and use it across all your tabs and windows.</p><h2>The Simple Todo List Extension We're Building</h2><p>We'll create a todo list extension that lives in a popup. Users can add, view, and delete tasks. Completed tasks will be visually marked with a strikethrough, and all data persists using Chrome's storage API. The UI is clean, minimal, and actually works as expected.</p><p>This is how finished extension looks like:</p><img src="/blog/images/ad86e139f2bf2b6b/todo.png" alt="Todo list chrome extension" width="300"><h2>What You'll Need</h2><p>The only thing you need is a text editor (VS Code, Sublime, or even Notepad) and Chrome browser. No npm, no build tools, no complicated setup. Just create a folder and add a few files.</p><h2>Step 1: Create Your Project Folder</h2><p>Create a new folder on your computer called <code>my-todo-extension</code>. This is where all your extension files will live.</p><pre><code>my-todo-extension/
├── manifest.json
├── popup.html
├── popup.css
├── popup.js
└── icon.png</code></pre><h2>Step 2: Create an Icon File</h2><p>Chrome requires at least a 128x128 pixel icon for your extension. You can create a simple icon using any image editor, Figma, or an online tool. Save it as <code>icon.png</code> in your <code>my-todo-extension</code> folder.</p><p>If you don't have an icon ready, you can create a simple one: just make a 128x128 pixel PNG file with a solid color background and some text or simple design. Chrome needs this icon to display your extension in the toolbar.</p><h2>Step 3: Create the manifest.json File</h2><p>The manifest.json file is the most important file in your extension. It tells Chrome essential information about your extension like its name, version, permissions, and which files to use.</p><p>Create a file named <code>manifest.json</code> and add the following code:</p><pre><code class="language-json">{
  "manifest_version": 3,
  "name": "Simple Todo List",
  "version": "1.0",
  "description": "A simple and elegant todo list extension",
  "permissions": ["storage"],
  "action": {
    "default_title": "My Todo List",
    "default_popup": "popup.html",
    "default_icon": "icon.png"
  }
}</code></pre><h3>What this does:</h3><ul><li><p><strong>manifest_version: 3</strong> tells Chrome to use the latest manifest format</p></li><li><p><strong>permissions: ["storage"]</strong> allows us to save todos using Chrome's storage API</p></li><li><p><strong>default_popup</strong> points to the HTML file that shows when you click the extension icon</p></li><li><p><strong>default_icon</strong> is the icon that appears in your toolbar</p></li></ul><h2>Step 4: Create the popup.html File</h2><p>The popup HTML is the UI that shows when users click your extension icon. Create a file named <code>popup.html</code> and add the following code:</p><pre><code class="language-html">&lt;!DOCTYPE html&gt;
&lt;html lang="en"&gt;
&lt;head&gt;
  &lt;meta charset="UTF-8"&gt;
  &lt;meta name="viewport" content="width=device-width, initial-scale=1.0"&gt;
  &lt;title&gt;Todo List&lt;/title&gt;
  &lt;link rel="stylesheet" href="popup.css"&gt;
&lt;/head&gt;
&lt;body&gt;
  &lt;div class="container"&gt;
    &lt;h1&gt;To-Do List&lt;/h1&gt;

    &lt;div class="input-section"&gt;
      &lt;input
        type="text"
        id="todoInput"
        placeholder="Add your task"
        autocomplete="off"
      &gt;
      &lt;button id="addBtn"&gt;ADD&lt;/button&gt;
    &lt;/div&gt;

    &lt;ul id="todoList" class="todo-list"&gt;&lt;/ul&gt;

    &lt;div id="emptyState" class="empty-state"&gt;
      &lt;p&gt;No tasks yet. Add one to get started!&lt;/p&gt;
    &lt;/div&gt;
  &lt;/div&gt;

  &lt;script src="popup.js"&gt;&lt;/script&gt;
&lt;/body&gt;
&lt;/html&gt;</code></pre><p>This HTML creates a clean interface with an input field for new todos, an ADD button, and a list to display todos.</p><h2>Step 5: Create the popup.css File</h2><p>Now let's add styling that creates a clean, elegant UI. Create a file named <code>popup.css</code>:</p><pre><code class="language-css">* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

body {
  width: 420px;
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
    'Helvetica Neue', sans-serif;
  margin: 0;
}

.container {
  padding: 24px;
  background: white;
  min-height: 500px;
  border-radius: 12px;
  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.1);
}

h1 {
  font-size: 28px;
  font-weight: 700;
  color: #1a1a1a;
  margin-bottom: 24px;
}

.input-section {
  display: flex;
  gap: 10px;
  margin-bottom: 24px;
}

#todoInput {
  flex: 1;
  padding: 12px 16px;
  border: 1px solid #e0e0e0;
  border-radius: 8px;
  font-size: 15px;
  outline: none;
  background: #f5f5f5;
  transition: all 0.3s ease;
}

#todoInput:focus {
  background: white;
  border-color: #ff6b6b;
  box-shadow: 0 0 0 3px rgba(255, 107, 107, 0.1);
}

#addBtn {
  padding: 12px 28px;
  background: #ff6b6b;
  color: white;
  border: none;
  border-radius: 8px;
  font-weight: 700;
  font-size: 15px;
  cursor: pointer;
  transition: all 0.3s ease;
}

#addBtn:hover {
  background: #ff5252;
  transform: translateY(-2px);
  box-shadow: 0 4px 12px rgba(255, 107, 107, 0.3);
}

#addBtn:active {
  transform: translateY(0);
}

.todo-list {
  list-style: none;
  margin-bottom: 16px;
}

.todo-item {
  display: flex;
  align-items: center;
  padding: 16px;
  background: #f8f9fa;
  border-radius: 8px;
  margin-bottom: 10px;
  gap: 12px;
  transition: all 0.2s ease;
}

.todo-item:hover {
  background: #f0f1f3;
}

.todo-item input[type='checkbox'] {
  width: 20px;
  height: 20px;
  cursor: pointer;
  accent-color: #ff6b6b;
  flex-shrink: 0;
  border-radius: 50%;
}

.todo-item.completed input[type='checkbox'] {
  accent-color: #ff6b6b;
}

.todo-item span {
  flex: 1;
  font-size: 15px;
  color: #333;
  word-break: break-word;
  transition: all 0.2s ease;
}

.todo-item.completed span {
  text-decoration: line-through;
  color: #999;
  opacity: 0.7;
}

.delete-btn {
  background: transparent;
  color: #ff6b6b;
  border: none;
  padding: 6px 8px;
  cursor: pointer;
  font-size: 18px;
  transition: all 0.2s ease;
  flex-shrink: 0;
  display: flex;
  align-items: center;
  justify-content: center;
}

.delete-btn:hover {
  color: #ff5252;
  transform: scale(1.2);
}

.empty-state {
  text-align: center;
  padding: 40px 20px;
  color: #999;
  font-size: 14px;
}

.empty-state.hidden {
  display: none;
}</code></pre><p>This CSS creates a modern, clean interface with smooth transitions and a professional look. The container has a subtle shadow and rounded corners, while completed tasks show with a strikethrough and reduced opacity.</p><h2>Step 6: Create the popup.js File</h2><p>Now for the JavaScript logic that makes everything work. Create a file named <code>popup.js</code> and add the following code:</p><pre><code class="language-jsx">const todoInput = document.getElementById('todoInput');
const addBtn = document.getElementById('addBtn');
const todoList = document.getElementById('todoList');
const emptyState = document.getElementById('emptyState');

// Load todos when popup opens
document.addEventListener('DOMContentLoaded', loadTodos);

// Add todo on button click
addBtn.addEventListener('click', addTodo);

// Add todo on Enter key press
todoInput.addEventListener('keypress', (e) =&gt; {
  if (e.key === 'Enter') {
    addTodo();
  }
});

function addTodo() {
  const todoText = todoInput.value.trim();

  if (todoText === '') {
    todoInput.focus();
    return;
  }

  const todo = {
    id: Date.now(),
    text: todoText,
    completed: false
  };

  chrome.storage.local.get('todos', (result) =&gt; {
    const todos = result.todos || [];
    todos.push(todo);
    chrome.storage.local.set({ todos }, () =&gt; {
      todoInput.value = '';
      todoInput.focus();
      loadTodos();
    });
  });
}

function loadTodos() {
  chrome.storage.local.get('todos', (result) =&gt; {
    const todos = result.todos || [];
    todoList.innerHTML = '';

    if (todos.length === 0) {
      emptyState.classList.remove('hidden');
      return;
    }

    emptyState.classList.add('hidden');

    todos.forEach((todo) =&gt; {
      const li = document.createElement('li');
      li.className = `todo-item ${todo.completed ? 'completed' : ''}`;

      const checkbox = document.createElement('input');
      checkbox.type = 'checkbox';
      checkbox.checked = todo.completed;
      checkbox.addEventListener('change', () =&gt; toggleTodo(todo.id));

      const span = document.createElement('span');
      span.textContent = todo.text;

      const deleteBtn = document.createElement('button');
      deleteBtn.className = 'delete-btn';
      deleteBtn.textContent = '✕';
      deleteBtn.addEventListener('click', () =&gt; deleteTodo(todo.id));

      li.appendChild(checkbox);
      li.appendChild(span);
      li.appendChild(deleteBtn);

      todoList.appendChild(li);
    });
  });
}

function toggleTodo(id) {
  chrome.storage.local.get('todos', (result) =&gt; {
    const todos = result.todos || [];
    const todo = todos.find(t =&gt; t.id === id);

    if (todo) {
      todo.completed = !todo.completed;
      chrome.storage.local.set({ todos }, loadTodos);
    }
  });
}

function deleteTodo(id) {
  chrome.storage.local.get('todos', (result) =&gt; {
    let todos = result.todos || [];
    todos = todos.filter(t =&gt; t.id !== id);
    chrome.storage.local.set({ todos }, loadTodos);
  });
}</code></pre><h3>Understanding Chrome Storage API</h3><p>Before diving into the code, let's understand how Chrome's storage system works. Unlike regular web pages that lose data when you refresh, Chrome extensions can store data persistently using the <code>chrome.storage</code> API.</p><p>There are two types of Chrome storage:</p><ul><li><p><strong>chrome.storage.local</strong>: Data stored locally on your device (what we're using)</p></li><li><p><strong>chrome.storage.sync</strong>: Data synced across all your Chrome instances</p></li></ul><p>The storage API is asynchronous, meaning you need to use callbacks or promises. Every time you want to save or retrieve data, you call <code>chrome.storage.local.get()</code> to read and <code>chrome.storage.local.set()</code> to write.</p><h3>What this code does:</h3><ul><li><p><strong>addTodo()</strong> creates a new todo object with a unique ID and saves it to Chrome storage</p></li><li><p><strong>loadTodos()</strong> fetches all saved todos from storage and dynamically creates the UI elements</p></li><li><p><strong>toggleTodo()</strong> finds a specific todo by ID, flips its completed status, and saves the changes</p></li><li><p><strong>deleteTodo()</strong> removes a todo from the array and updates storage</p></li><li><p><strong>Event handling</strong> uses proper <code>addEventListener()</code> methods for better security and maintainability</p></li></ul><h3>Why We Use Proper Event Handling</h3><p>Instead of inline event handlers like <code>onclick="deleteTodo(123)"</code>, we use <code>addEventListener()</code>. This approach:</p><ul><li><p>Prevents XSS attacks by avoiding <code>innerHTML</code> with user content</p></li><li><p>Makes the code more maintainable and testable</p></li><li><p>Follows modern JavaScript best practices</p></li><li><p>Ensures events work reliably across different browsers</p></li></ul><h2>Step 7: Load Your Extension into Chrome</h2><p>Now comes the fun part. Let's load your extension into Chrome:</p><ol><li><p>Open Chrome and go to <code>chrome://extensions/</code></p></li><li><p>Enable <strong>"Developer mode"</strong> by toggling the switch in the top right corner</p></li><li><p>Click <strong>"Load unpacked"</strong></p></li><li><p>Navigate to your <code>my-todo-extension</code> folder and select it</p></li><li><p>Your extension is now loaded!</p></li></ol><p>You should see your Todo List extension icon in your Chrome toolbar. Click it and start adding todos. Check a todo off to mark it as complete, and click the ✕ to delete it. Everything persists across sessions!</p><h2>What You've Just Built</h2><p>You've created a fully functional Chrome extension with persistent storage and a clean, elegant UI. The extension:</p><ul><li><p><strong>Stores data locally</strong> using Chrome's storage API that survives browser restarts</p></li><li><p><strong>Handles all user interactions</strong> smoothly with proper event handling</p></li><li><p><strong>Shows immediate visual feedback</strong> for every action</p></li><li><p><strong>Persists todos</strong> across browser sessions and computer restarts</p></li><li><p><strong>Uses secure DOM manipulation</strong> methods that prevent common web vulnerabilities</p></li><li><p><strong>Works with vanilla JavaScript</strong> only - no frameworks needed</p></li></ul><h2>Key Takeaways</h2><p>Creating a Chrome extension is simpler than most people think. You need just a manifest file, HTML for the UI, CSS for styling, and JavaScript for functionality. The manifest acts as your extension's blueprint, telling Chrome exactly what to load and what permissions you need.</p><p>The most important part is understanding how Chrome's storage API works and ensuring your data actually persists. Unlike regular web pages, extensions can store data that survives browser restarts, making them perfect for productivity tools like todo lists.</p><p>Using proper event handling and secure DOM manipulation methods makes your extension more reliable and secure. The <code>chrome.storage</code> API is your gateway to creating truly useful extensions that remember user data.</p><p>Start simple, test frequently, and gradually add features. Once you understand the basics, you can expand to more complex extensions that interact with web pages, manage tabs, or integrate with external APIs.</p><p>Happy extending!</p>

How to guide

How to Create a Chrome Extension: Build Your First Extension in 30 Minutes