or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-primer--octicons

A scalable set of 336 handcrafted SVG icons from GitHub's Primer design system

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@primer/octicons@19.16.x

To install, run

npx @tessl/cli install tessl/npm-primer--octicons@19.16.0

index.mddocs/

Primer Octicons

Primer Octicons is a comprehensive collection of 336 scalable SVG icons designed and maintained by GitHub as part of their Primer design system. The package provides programmatic access to icon data, SVG markup, and metadata, making it ideal for web applications, desktop applications, and any project requiring high-quality, consistent iconography with GitHub's design language.

Package Information

  • Package Name: @primer/octicons
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install @primer/octicons

Core Imports

const octicons = require("@primer/octicons");

For ES modules:

import * as octicons from "@primer/octicons";

Basic Usage

const octicons = require("@primer/octicons");

// Access an icon
const alertIcon = octicons.alert;

// Get basic icon information
console.log(alertIcon.symbol);    // "alert"
console.log(alertIcon.keywords);  // ["warning", "triangle", "exclamation", "point"]

// Generate SVG markup
const svg = alertIcon.toSVG();
console.log(svg); // <svg version="1.1" width="16" height="16"...>

// Generate SVG with custom options
const customSvg = alertIcon.toSVG({
  class: "my-icon warning-icon",
  "aria-label": "Warning message",
  width: 24
});

Architecture

Primer Octicons provides a simple but powerful architecture:

  • Icon Objects: Each icon is an object containing metadata and rendering capabilities
  • Lazy Loading: Icon data is loaded from a generated JSON file containing all SVG paths and metadata
  • Size Selection: Automatically chooses the best SVG size variant based on requested dimensions
  • Keyword System: Each icon includes searchable keywords for discovery
  • CSS Integration: Includes default CSS classes and supports custom styling

Capabilities

Icon Access and Properties

Access individual icons and their metadata through the main export object.

// Main export - object containing all 336 icons
const octicons = {
  // Each icon is an object with the following properties:
  [iconName]: {
    /** The icon name (same as the object key) */
    symbol: string,
    /** Array of keywords/aliases for searchability */
    keywords: string[],
    /** Available size variants with SVG data */
    heights: {
      [height]: {
        /** Natural width of the SVG at this height */
        width: number,
        /** SVG path elements as HTML string */
        path: string,
        /** Default HTML attributes for the SVG element */
        options: {
          version: string,
          width: number,
          height: number,
          viewBox: string,
          class: string,
          "aria-hidden": string
        },
        /** Parsed SVG Abstract Syntax Tree */
        ast: {
          name: string,
          type: string,
          value: string,
          attributes: object,
          children: object[]
        }
      }
    },
    /** Generate complete SVG markup */
    toSVG: function(options)
  }
};

Usage Examples:

// Access icon properties
const xIcon = octicons.x;
console.log(xIcon.symbol);    // "x"
console.log(xIcon.keywords);  // ["remove", "close", "delete"]

// Check available sizes
console.log(Object.keys(xIcon.heights)); // ["16", "24"]

// Get size-specific data
const size16 = xIcon.heights[16];
console.log(size16.width);    // 16
console.log(size16.path);     // "<path d=\"...\"></path>"

// Multi-word icon names require bracket notation
const arrowRight = octicons['arrow-right'];
// octicons.arrow-right would not work

SVG Generation

Generate complete SVG markup with customizable options for styling and accessibility.

/**
 * Generate complete SVG markup as a string
 * @param {object} [options] - Customization options for the SVG element
 * @param {string} [options.class] - Additional CSS classes to add to the SVG element
 * @param {string} [options.aria-label] - Accessibility label (removes aria-hidden, adds role="img")
 * @param {number} [options.width] - Custom width (height calculated proportionally)
 * @param {number} [options.height] - Custom height (width calculated proportionally)
 * @returns {string} Complete SVG element as HTML string
 */
toSVG(options);

Usage Examples:

// Basic SVG generation (16px default)
const basicSvg = octicons.alert.toSVG();
// <svg version="1.1" width="16" height="16" viewBox="0 0 16 16" 
//      class="octicon octicon-alert" aria-hidden="true">
//   <path d="..."></path>
// </svg>

// Custom CSS classes
const styledSvg = octicons.check.toSVG({ 
  class: "success-icon text-green" 
});
// Adds classes: "octicon octicon-check success-icon text-green"

// Accessibility support
const accessibleSvg = octicons.alert.toSVG({ 
  "aria-label": "Warning: Check your input" 
});
// Adds aria-label and role="img", removes aria-hidden

// Custom sizing (automatically selects best size variant)
const largeSvg = octicons.star.toSVG({ width: 32 });
// Uses 24px variant, scaled to 32px

// Size with both dimensions
const customSvg = octicons.repo.toSVG({ width: 20, height: 24 });
// Uses 24px variant with custom dimensions

Size Selection and Scaling

Octicons automatically selects the most appropriate size variant based on requested dimensions.

Size Selection Logic:

  • Default size: 16px height when no size specified
  • Available sizes: Most icons have 16px and 24px variants, some icons may have additional sizes
  • Selection algorithm: Finds the largest natural height that is less than or equal to the requested size, falling back to the first available size if none qualify
  • Proportional scaling: When only width or height is specified, the other dimension is calculated proportionally based on the selected size variant's aspect ratio

Usage Examples:

// Default size (16px)
octicons.x.toSVG(); // Uses 16px variant

// Request 20px height - uses 16px variant (largest ≤ 20)
octicons.x.toSVG({ height: 20 });

// Request 24px height - uses 24px variant (exact match)
octicons.x.toSVG({ height: 24 });

// Request 30px height - uses 24px variant (largest ≤ 30)
octicons.x.toSVG({ height: 30 });

// Request 12px height - uses 16px variant (no smaller variant available)
octicons.x.toSVG({ height: 12 });

// Width-based sizing (uses width or height, whichever is provided)
octicons.x.toSVG({ width: 48 }); // Selects variant based on width=48

Available Icons

The package includes 336 icons across various categories:

Navigation and Arrows

  • arrow-left, arrow-right, arrow-up, arrow-down, arrow-both
  • arrow-small-left, arrow-small-right, arrow-small-up, arrow-small-down
  • arrow-up-left, arrow-up-right, arrow-down-left, arrow-down-right
  • chevron-left, chevron-right, chevron-up, chevron-down

Status and Alerts

  • alert, alert-fill, check, x, circle-slash
  • stop, blocked, verified, unverified

User Interface

  • gear, three-bars, kebab-horizontal, apps
  • home, search, bell, mail
  • heart, star, bookmark, eye

Development and Git

  • code, terminal, repo, git-branch
  • git-commit, git-merge, git-pull-request
  • issue-opened, issue-closed, bug

Files and Folders

  • file, file-code, file-directory, folder
  • archive, package, download, upload

Communication

  • comment, comment-discussion, mention
  • people, person, organization

And many more categories including accessibility, AI/technology, time/calendar, security, and specialized GitHub features.

Finding Icons:

// Get all available icon names
const allIcons = Object.keys(octicons);
console.log(`Total icons: ${allIcons.length}`); // 336

// Search by keywords
const alertIcons = allIcons.filter(name => 
  octicons[name].keywords.includes('warning')
);

// Icons with multi-word names use hyphens and bracket notation
const fileIcons = allIcons.filter(name => name.startsWith('file-'));
fileIcons.forEach(name => {
  const icon = octicons[name]; // Use bracket notation: octicons[name]
  console.log(`${name}: ${icon.keywords.join(', ')}`);
});

CSS Styling

Default Classes

All generated SVGs include these CSS classes:

  • octicon: Base class for all Octicons
  • octicon-{icon-name}: Specific class for each icon (e.g., octicon-alert)

Recommended CSS

Include the package's CSS for consistent styling:

/* From @primer/octicons/index.scss or build/build.css */
.octicon {
  display: inline-block;
  vertical-align: text-top;
  fill: currentColor;
  overflow: visible;
}

Custom Styling

// Add custom classes
const customIcon = octicons.star.toSVG({
  class: "favorite-icon text-yellow-500 hover:text-yellow-600"
});

// Icons inherit text color by default
// CSS: .text-blue { color: blue; }
// Result: blue icons

Error Handling and Edge Cases

Invalid Icon Names:

const invalid = octicons.nonexistent; // undefined
if (invalid) {
  // Safe to use
  const svg = invalid.toSVG();
}

Multi-word Names:

// Correct - use bracket notation
const arrowRight = octicons['arrow-right'];

// Incorrect - will not work
// const arrowRight = octicons.arrow-right; // Syntax error

Size Edge Cases:

// Very small sizes use smallest available variant
octicons.x.toSVG({ height: 1 }); // Uses 16px variant, scaled down

// Very large sizes use largest available variant  
octicons.x.toSVG({ height: 1000 }); // Uses 24px variant, scaled up

// Invalid options are ignored
octicons.x.toSVG({ invalidOption: true }); // Works normally

Performance Considerations

  • Icon Data: All 336 icons are loaded when the module is required
  • SVG Generation: toSVG() is a lightweight operation that builds strings
  • Caching: Consider caching generated SVG strings for repeated use
  • Size Selection: Size selection algorithm runs on each toSVG() call
// Cache frequently used SVGs
const alertSvg = octicons.alert.toSVG({ class: "warning" });
// Reuse alertSvg string instead of regenerating