octicons

@primer/octicons is the official npm package for Octicons, GitHub’s open-source library of scalable SVG icons. It is the Node.js/JavaScript library in the primer/octicons monorepo, which also ships React components, styled-components bindings, a Ruby gem, and a Jekyll plugin from the same source icon set.

Each icon is precompiled into a JSON data file at build time from raw SVG sources using an internal build pipeline (SVGO for optimization, svgson for AST parsing). At runtime, the package exposes a toSVG(options) method per icon that renders ready-to-inject SVG markup, automatically choosing between 16px and 24px source variants, applying accessible defaults (aria-hidden, or role="img" with a supplied aria-label), and merging in caller-supplied CSS classes and sizing. A companion keywords.json file maps conceptual search terms to icon names, the same alias data GitHub’s own icon picker uses.

What You Get

• The full Octicons SVG set (749+ icons) as importable JS data, keyed by icon name
• A toSVG() renderer per icon supporting custom width, height, class, and aria-label options
• A natural-height fallback that auto-selects the best-fitting 16px or 24px source SVG for a requested size
• keywords.json, a maintained search-alias map for building icon pickers
• A companion build.css stylesheet for baseline icon normalization

Common Use Cases

• Rendering GitHub-style icons in Node.js or browser JavaScript apps without a build-time SVG loader
• Building an icon search/picker experience using the bundled keyword aliases
• Matching UI iconography to GitHub’s own product surfaces (PRs, issues, actions) in developer tools
• Server-side rendering icons as inline SVG strings for static site generators

Under The Hood

Architecture The node package (lib/octicons_node) is a thin wrapper: a compiled index.ts requires a pre-built build/data.json, generated at the monorepo root by script/build.ts, which walks every icons/**/*.svg file, parses each with svgson/cheerio to extract path, width, height, and merges in keywords.json aliases via lodash.merge into one flat data structure keyed by icon name. At runtime, a top-level loop decorates each entry with a symbol, per-height options (viewBox/class/aria attributes), and a closure-bound toSVG() function that uses a closestNaturalHeight() helper to pick the nearest defined pixel size at or below the requested height. It’s a clean two-stage build/runtime split — no classes or DI, just a flat object mutated once at module load — and the same build output fans out to octicons-react, octicons_styled, and the Ruby/Jekyll packages elsewhere in the Turborepo workspace.

Tech Stack TypeScript compiled via tsc to CommonJS (main: index.js, using require() for data.json and object-assign). Monorepo build tooling includes svgo 3.3.4 for SVG optimization, svgson for AST parsing, cheerio for reading raw SVG attributes, globby for glob discovery, and turbo orchestrating npm workspaces (lib/*, examples/*). Tests run on Vitest 4.x with @vitest/browser and Playwright for browser-mode assertions; linting via ESLint 10 with eslint-plugin-github, formatting via Prettier with GitHub’s shared config. Releases are cut through Changesets (@changesets/cli, @changesets/changelog-github) and published via GitHub Actions.

Code Quality The package’s Vitest suite exercises the full public contract of toSVG(): presence of every icon, required SVG attributes (version, aria-hidden, width, height, viewBox, class, data-component), custom class merging, aria-label handling, and both width- and height-driven size selection. Types are used throughout (Options, HeightData, IconData), though the imported data.json is cast rather than schema-validated, so a malformed build artifact would fail silently rather than throw early. CI runs lint, type-check, and test scripts separately per the repo’s GitHub Actions workflow.

API Design The public surface is intentionally minimal: index into the exported object by icon name, then call .toSVG(options). Multi-word icon names require bracket notation, which the README calls out explicitly as a common gotcha. Sizing accepts either width or height and derives the other proportionally, and accessibility is opt-in-safe by default (hidden unless labeled). This ergonomic shape is functionally comparable to other SVG icon libraries (Feather, Lucide) rather than a novel API, but the wider monorepo’s differentiator is process and reach: a single icons/ source of truth feeds five separate ecosystem bindings (JS, React, styled-components, Ruby gem, Jekyll) through a formal Figma-to-PR design review pipeline documented in CONTRIBUTING.md, plus a hand-curated keyword alias index most icon-only packages don’t ship.