Material Icons for GitHub: file type icons in your browser

What the extension actually changes on github.com

Material Icons for GitHub is a browser extension that enhances repository file browsers when navigating github.com. It replaces the default file and folder icons with Material Design icons tailored to each file type, tool and purpose in the project.

That is the whole feature, and it is worth being precise about the scope. The extension works on the file browser view of a repository, the tree you browse to find a file, and it substitutes the icon that GitHub renders next to each entry. It is not a theme for the entire site, and it is not a file preview tool.

The extension is published in the Chrome Web Store, the Microsoft Edge Addons Store and Firefox Addons, so for those three browsers the install is a store click. For Safari on macOS the README is explicit that there is no App Store release yet, and that you can build and install it yourself with Xcode, Node.js 24.15 or newer and a free Apple account.

The original extension was developed with Richard Lam, and the project now sits with Material Extensions, the organisation that maintains the VS Code icon theme this work depends on.

Every icon and every file assignment is pulled from the VS Code icon theme

The dependency structure is the design. The extension is based on and dependent on the popular Material Icon Theme extension for Visual Studio Code, and all icons and file assignments on this project are pulled directly from that project. The README adds that any praise or design issues should be raised on the original repository.

That is a clean division of labour. There is one place where the mapping from file name to icon is decided, the VS Code theme, and this repository is a browser-shaped consumer of it. A user who thinks a Rust file should have a different icon has a single place to argue about it, and the browser extension follows along.

The dependency is explicit in package.json, where material-icon-theme is pinned at 5.39.0 as a regular runtime dependency, and the README carries a badge recording the theme version the extension was last built with, v5.39.0.

The build scripts reflect the same arrangement. The default build re-downloads dependencies from the upstream icon theme repository, and there is a separate script that builds only files from the src folder without re-downloading from upstream. The development section also has a script to rebuild the extension logos from src/logo.svg, needed only when that source file changes.

So the extension follows the upstream theme rather than forking it, which means it inherits the theme's release cadence and the theme's design decisions, and the risk that comes with them.

The build pipeline, from source to a store upload

The npm scripts tell you how the project is put together, and they are more interesting than a typical extension's.

A local build is a single command:

npm run build

The build script itself is composed of three steps, running build-src, then a type safety check, then bundle. The prebuild hook removes any zip files and the dist directory first, so a build never mixes old artefacts with new ones.

The other scripts handle the store upload and the Safari path. The bundle script zips the dist folder for upload to the Chrome Web Store and Firefox, and the README warns that this script needs Zip to be available on PATH. The build-src script is the one that pulls from the upstream theme, and it doubles as the Safari build step, producing a Safari Web Extension bundle in dist/safari.

The Safari packaging step is separate again:

npm run package-safari

That produces an Xcode project for local Safari testing or App Store distribution, and it requires Xcode with safari-web-extension-packager available on PATH.

The toolchain is modern and TypeScript-first. The main entry point is src/main.ts, the build uses tsx to run the build scripts and esbuild to bundle, and the linting is done with Biome through a biome.jsonc configuration rather than the older ESLint and Prettier pairing. There is a playwright.config.ts and an e2e/ directory, so the extension is tested in a real browser rather than only in jsdom, and vitest.config.ts with jsdom 30.1.1 and testing-library covers the unit level. commitlint and husky are wired in, and renovate.json is present for dependency updates.

Safari has its own constraints, and the CSP workaround is the interesting part

The Safari instructions are the most involved part of the README, and they explain a browser difference that shapes the implementation.

You build the extension and generate the Xcode project, then open the generated project, add your Apple ID in Xcode under Settings and Accounts, and under Signing and Capabilities set Team to your Personal Team for both the macOS app and the macOS extension targets. Then you select the macOS scheme named Material Icons for GitHub and run it, and move the built app to /Applications so the extension stays installed. Finally, in Safari under Settings and Extensions, you enable the extension and allow it on github.com.

If the extension does not appear, the README tells you to enable the feature for web developers under Settings and Advanced, and then to allow unsigned extensions under Settings and Developer. The iOS targets are generated as well, but they are described as untested.

The technical reason for a different approach on Safari is stated at the end of that section. Safari applies the page's Content Security Policy to extension URLs, so on Safari the icons are loaded as data: URLs through the background script.

That is a genuinely interesting constraint. A Content Security Policy on github.com governs which URLs the page is allowed to load, and in a Safari web extension the page's policy applies to the extension's own resources in a way that does not happen in Chromium. Loading the icons as data: URLs sidesteps the policy question entirely, at the cost of putting the image bytes into the message traffic. The same extension therefore ships with a different icon delivery path depending on the browser.

Dependencies that say what the extension is made of

The dependency list in package.json is a decent description of the architecture, and it explains a design decision that would otherwise be puzzling.

The runtime dependencies are React 19.3.0 and react-dom 19.3.0, with @mui/material 9.4.0 and @mui/icons-material 9.4.0, plus @emotion/react and @emotion/styled. The extension builds its icon list and file picker interface as a React application using the MUI component library, which is where Material Design rendering comes from. The other two runtime entries are webextension-polyfill 0.12.0, which is what lets the same code target Chrome, Edge and Firefox, and material-icon-theme 5.39.0, which supplies the icon data.

So the extension is a React app rendered inside the browser's file tree, which is a heavier approach than injecting icon images directly into the DOM. The payoff is consistent rendering and a normal component model; the cost is a bundle larger than the icons alone would need.

There is also @mui/icons-material as a separate dependency, which is the general-purpose Material icon set, separate from the theme-derived icons.

On the tooling side, the development dependencies include TypeScript 7.0.2, vitest 5.0.2, Playwright 1.63.0, web-ext 10.7.0, which is Mozilla's extension tool, nodemon, npm-run-all, rimraf, sharp for image processing, and lint-staged. The presence of web-ext alongside Playwright suggests the Firefox build path is exercised with Mozilla's own tooling rather than only through the bundler.

Licence, release cadence and who to complain to

The licence is MIT, which covers the extension code without obligation beyond attribution and notice. The upstream VS Code icon theme is a separate project with its own terms, and if you are redistributing the extension you are redistributing icons that came from there, so the attribution chain matters.

On cadence, the release list is dense. v1.17.1 was published on 2026-10-02, v1.17.0 on the same day, and v1.16.4 on 2026-08-24. The last push to the repository was on 2026-10-17, and the repository is not archived, so the extension is being worked on directly rather than sitting still.

The two releases on the same day are a small signal about how this project operates. When the upstream icon theme publishes a new version, the extension is rebuilt and republished, so a version bump here often means an upstream bump rather than a change to the extension itself. That is what the upstream-dependency badge is for, and it is worth checking if you are debugging an icon that looks wrong.

The support boundary is the last thing to know. The README routes design feedback to the original VS Code theme repository, and the CHANGELOG.md at the root holds the version history. The repository also carries a .devcontainer/ directory, a .husky/ directory for git hooks, a renovate.json for automated dependency updates, and an .editorconfig.

The original extension was developed with Richard Lam, and Material Extensions is listed as the package author, with a contact address in package.json.

Editorial conclusion

Adopt Material Icons for GitHub if you spend time in repository file trees and the default generic file icons slow you down, since the extension is small, published for the three main Chromium and Firefox stores, and updated on the same cycle as the upstream icon theme. Do not adopt it if you are on Safari and unwilling to build from source, because there is no App Store release and the Safari path needs Xcode, Node.js and a personal team signing setup. Before you install, check that the icon assignments you rely on exist in the upstream theme, and remember that every design or assignment issue belongs on the VS Code theme repository rather than here.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. material-extensions/material-icons-browser-extension on GitHub
4. README
5. Releases