Primer Octicons is an open-source set of handcrafted SVG icons built by GitHub for GitHub, distributed as a collection of libraries for JavaScript, React, Ruby, and Jekyll. The repository description calls it "A scalable set of icons handcrafted with ❤️ by GitHub," and it currently has over 8,700 stars on GitHub.
What is Primer Octicons?
Primer Octicons is a scalable icon library maintained by GitHub as part of the Primer design system. It provides a set of SVG icons and exposes them through several packages in the primer/octicons repository, each targeting a different platform: @primer/octicons for Node.js, @primer/octicons-react and @primer/styled-octicons for React, octicons gem for Ruby, octicons_helper for Rails, and jekyll-octicons for Jekyll. The code is released under the MIT license, and GitHub logos within the set are subject to the GitHub logo guidelines.
Key Features
- SVG-native icons — All icons are SVG files, so they scale smoothly at any resolution and can be styled with CSS.
- Multiple language packages — Six official libraries are provided, covering Node.js, React, Ruby, Rails, and Jekyll, each with a package-specific API.
- React component library —
@primer/octicons-reactdelivers icons as installable React components, while@primer/styled-octiconsextends them with Styled System props. - Ruby ecosystem support — The
octiconsgem offers a Ruby API,octicons_helperintegrates with Rails, andjekyll-octiconsworks as a plugin for Jekyll static sites. - Open contribution flow — The repository welcomes bug reports and feature ideas via the issue templates, and has a dedicated icon review request process for GitHub staff.
- Used by GitHub — The icons are built "by GitHub for GitHub," ensuring they match the visual style of GitHub's own interfaces.
Who is it for?
- Front-end developers who want a consistent set of icons that match GitHub's design language, available as npm packages or React components.
- React developers who prefer to import icon components directly into their JSX rather than managing raw SVG strings.
- Ruby and Rails developers who need server-side icon rendering in views, email templates, or other Ruby-generated content.
- Jekyll site maintainers who want to include icons in static documentation or blogs using the jekyll-octicons plugin.
Use cases
- Web applications: install
@primer/octicons-reactand import icons as React components in menus, buttons, status indicators, and empty states. - Rails projects: use
octicons_helperto generate icon markup from Ruby code, keeping icons consistent across pages. - Documentation sites: leverage
jekyll-octiconsin a Jekyll build to output icon SVGs without manually editing image files.
FAQ
Is Primer Octicons free to use?
Yes, the code is released under the MIT license, so you can use the icon libraries in commercial and personal projects. The GitHub logos included in the set are an exception and must follow the GitHub logo guidelines.
What packages are available?
The main packages are @primer/octicons (Node.js), @primer/octicons-react (React), @primer/styled-octicons (React + Styled System), octicons (Ruby gem), octicons_helper (Rails helper), and jekyll-octicons (Jekyll plugin).
How do I contribute an icon?
You can open an issue in the primer/octicons repository using the appropriate issue template. GitHub staff can use the dedicated icon review request template to propose new icons for inclusion.
