# Primer Octicons: GitHub's SVG icon set and the libraries that ship it

> Octicons is a hand-built SVG icon set published by GitHub for its own interfaces and released under MIT. The repository is a monorepo of platform packages (Node, React, Ruby, Jekyll), and the interesting engineering is in how icon names, sizes and aliases are kept stable across all of them.

**primer/octicons** — A scalable set of icons handcrafted with ❤️ by GitHub

- Repository: https://github.com/primer/octicons
- Website: https://primer.style/octicons/
- Stars: 8,764 · Forks: 843
- Language: TypeScript
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/primer-octicons

## What Octicons is, and the problem it removes

Octicons is a set of SVG icons built by GitHub for GitHub, and the repository publishes that set to several language ecosystems at once. The problem it solves is not drawing icons. It is keeping one icon set consistent across a Node build, a React app, a Rails view layer and a Jekyll site without four teams redrawing the same glyph.

The audience is narrow and specific. You are building a developer tool, a documentation site, or an internal dashboard whose visual language already leans on GitHub's. You want an icon whose meaning a developer recognises without a legend. You also want the licence question settled: the code is MIT, while the GitHub logos carry separate logo guidelines, which matters because an octocat mark is not the same thing as a generic gear icon.

If you are outside that audience, the set will feel arbitrary. There is no illustration library here, no duotone variant, no icon for a concept GitHub has never needed to draw. That is a constraint of provenance, not an oversight.

## How the monorepo turns SVG files into six published packages

The repository is an npm workspace monorepo. The top level holds the source of truth in icons/, plus icon-metadata.json and keywords.json, and the build script writes a consolidated data file and an SVG output directory into lib/build. Every platform package under lib/ consumes that build output rather than parsing raw SVGs itself.

That single build step is the design decision worth noticing. Icon names, sizes and aliases are resolved once, at build time, and then handed to each language binding. The practical consequence is that the JavaScript API, the React components and the Ruby gem cannot drift apart on what an icon is called or which drawing a name points to.

The build is invoked through the root package scripts. The build script takes the icon glob, the metadata file and the output paths as arguments, which means the icon set is data, not code, and the packages are thin adapters over that data.

```bash
npm run build
```

Running that from the repository root regenerates lib/build/data.json and the lib/build/svg directory from icons/**/*.svg. There is also a separate svgo script that runs the SVG optimiser over the icons directory with svgo.config.mts, and a test script backed by vitest.

## Installing @primer/octicons-react and rendering a first icon

For a React application the package is @primer/octicons-react, which the README describes as React Octicons components. The README lists it in the Libraries table alongside @primer/octicons and @primer/styled-octicons, and links each name to its folder under lib/. The examples directory in the repository contains a Next.js example under examples/octicons-react-nextjs if you want to see the package wired into a real app shell.

The README does not print an install command for the React package, so the package name is the part to take from it:

```bash
npm install @primer/octicons-react
```

Once installed, you import the named component for the icon you want and pass a size. The README notes that the JavaScript and Ruby helpers retain their existing 24px output when callers omit width and height, and that an explicit 16px request selects the 16px drawing. So the default is not neutral. If you want the small artwork you have to ask for it.

The styled variant, @primer/styled-octicons, is described in the README as React Octicons components with Styled System props. The Node package, @primer/octicons, is described as a Node.js package with a JavaScript API, for cases where you are generating markup outside a React tree. The Ruby side splits three ways: the octicons gem for a Ruby API, octicons_helper for Rails views, and jekyll-octicons as a Jekyll plugin. All of them are versioned together; the release notes for this cycle list octicons_helper, octicons_gem and jekyll-octicons at 19.38.0.

## Icon names, aliases and the 16px trap

This is the part of the project that deserves the most attention, because the README documents a compatibility scheme that is easy to skim past and expensive to get wrong.

Some icon names have been renamed. The old names are preserved as compatibility names, and they keep their exports, CSS classes, symbol IDs and published build/svg paths. An aliasOf property in the icon data points at the canonical name, and a separate deprecated flag marks the aliases that are on their way out. Catalogues can filter aliasOf entries without breaking legacy lookups.

The trap is in the artwork. For bookmark-fill and repo-delete, the old names bookmark-filled and repo-deleted retain their 16px drawing at every display size. The canonical names now provide both natural sizes. So if you render the deprecated alias at 24px you get a 16px drawing scaled up, sitting next to a canonical icon that has real 24px artwork. The mismatch is visible.

The triangle family follows the same shape-based convention as the square family, with 16px and 24px artwork each. The name triangle-circle is a supported alias of play, and it retains both original circled drawings rather than the bare triangle. That is a deliberate exception: the alias does not collapse to the canonical shape, because doing so would change what the icon means. git-pull-request-unlisted is documented as providing 16px artwork only, so it is the one to check before you use it at a large size.

## Where Octicons is the wrong choice

The set is opinionated in a way that will not suit every project. There is no icon font in the repository, and no CDN-hosted stylesheet documented in the README, even though people search for both. If your build pipeline expects a webfont with ligatures, or a single CSS file you can drop in a link tag, you are looking at the wrong artifact: this project publishes SVG and language bindings, not a font.

Coverage is another boundary. The icon list is shaped by GitHub's product, so it is deep on version control, repositories, pull requests and CI, and thin on everything else. A marketing site, a consumer app or a data-visualisation tool will spend more time hunting for a near-miss than drawing the icon it actually needs.

There is also a governance limit worth stating plainly. The README says icon review requests are for GitHub staff only, routed through an internal issue template. If you are an outside contributor and you need an icon that does not exist, the documented path is a bug report or feedback issue, not an icon request. Your missing glyph may simply never be added, and you should plan to vendor your own SVG alongside the package rather than wait.

## Octicons against a general-purpose icon library

The obvious alternative is a general-purpose icon set with a broad catalogue and several weights, distributed as both SVG and font. The difference in approach is not quality, it is scope and naming discipline.

A broad library optimises for coverage and stylistic range. You pick a weight, a stroke style and a size, and you get thousands of glyphs across many domains. Octicons optimises for a fixed visual language and for name stability across releases. The compatibility table in the README is the clearest expression of that: the project is willing to carry deprecated aliases indefinitely, and to document exactly which drawing each alias preserves, rather than break downstream markup.

That trade goes both ways. You get fewer icons and no weight axis, but you also get a set where a rename does not silently change the pixels your users see, and where the same icon name resolves to the same drawing in a React component, a Rails helper and a Jekyll plugin. If your application is already in GitHub's visual neighbourhood, that consistency is worth more than catalogue size. If it is not, a general library will fit your product better and you will not spend the afternoon reading an alias table.

## Maintenance, licence and what an upgrade actually costs

The repository is not archived, and the last push was on 2026-09-18, which is three days before the date this article was written. The most recent releases in the same cycle are octicons_helper@19.38.0, octicons_gem@19.38.0 and jekyll-octicons@19.38.0, all published on 2026-09-18. The versioning is coordinated across the packages, and the repository uses Changesets for release management, with a version script and a changeset-publish script at the root.

The upgrade cost is low but not zero, and it is concentrated in the alias behaviour. Because compatibility names keep their exports and their build/svg paths, a version bump will not break your imports. What it can change is which drawing a name resolves to, particularly around the bookmark-fill, repo-delete and play families. A visual regression test over your rendered icons is the cheapest way to catch that, and the repository's own test setup is vitest with a browser runner, so the pattern is already established in-tree.

On licensing: the code is MIT, and the README states that the code licence applies to all other files. The GitHub logos are called out separately, with a pointer to GitHub's logo guidelines. Using an octocat mark in your product is a different question from using a generic chevron, and the README does not resolve it for you. The MIT grant covers the files in this repository; it does not grant trademark rights, and you should treat those as two separate decisions.

## Conclusion

Adopt Octicons if you are building a GitHub-adjacent interface, or if you want a single MIT-licensed SVG set with first-class React and Ruby packages rather than a hand-rolled sprite sheet. Do not adopt it if you need a wide stylistic range, a font build, or icons for concepts GitHub has no reason to draw; the set is built for GitHub's product surface, not for general illustration. Before you commit, check the canonical name of every icon you plan to use against the compatibility table in the README, because the deprecated aliases keep their old 16px artwork at every display size, and that difference will show up the moment you render a bookmark-fill or repo-delete alias next to its canonical sibling.

## FAQ

### How do I use Octicons in a React project?

Install @primer/octicons-react from npm and import the named component for the icon you want, then pass a size prop. The README notes that the JavaScript and Ruby helpers keep their existing 24px output when width and height are omitted, so pass an explicit 16 to get the small drawing.

### What is the main purpose of the Octicons icon set?

Octicons are a set of SVG icons built by GitHub for GitHub, and the repository publishes them as libraries for JavaScript, React, Ruby, Rails and Jekyll so the same icon set stays consistent across platforms.

### Where can I see the full list of Octicons names?

The README documents icon names and compatibility names in a table covering the bookmark-fill, repo-delete, triangle and play families, and points to the contributing guide for adding or updating icons. The repository also carries icon-metadata.json and keywords.json at the top level.

### Does Octicons ship an icon font or a CDN stylesheet?

The README describes the JavaScript, React, styled React, Ruby, Rails and Jekyll packages, and does not document a font build or a CDN-hosted stylesheet. The published artifacts are SVG and the language bindings over them.

### What licence does Octicons use?

The code licence is MIT, and the README states it applies to all other files. The GitHub logos are handled separately, with a pointer to GitHub's logo guidelines.

## Sources

- [License: MIT](https://github.com/primer/octicons/blob/main/LICENSE)
- [primer/octicons on GitHub](https://github.com/primer/octicons)
- [Project website](https://primer.style/octicons/)
- [README](https://github.com/primer/octicons/blob/main/README.md)
- [Releases](https://github.com/primer/octicons/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/primer-octicons