Technical Documentation: primer/octicons

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Primer Octicons

Libraries Copy Chapter

This repository contains several libraries. Each of them is in the lib/ folder and gives access to Octicons on a different platform/language.

JavaScript Copy Section

The octicons node.js library is the main JavaScript library. With a JavaScript API that can be used in a variety of applications.

Ruby Copy Section

Icon names and compatibility Copy Chapter

The shape-based triangle, triangle-circle, and triangle-fill names follow the square family. Each provides 16px and 24px artwork. git-pull-request-unlisted provides 16px artwork.

Compatibility names retain their exports, CSS classes, symbol IDs, and published build/svg paths. An aliasOf property identifies the canonical name in icon data; deprecated: true separately marks a deprecated alias. Catalogues can filter aliasOf entries without removing legacy lookups.

The canonical bookmark-fill and repo-delete names now provide both natural sizes. JavaScript and Ruby helpers retain their existing 24px output when callers omit width and height; an explicit 16px request selects the 16px drawing.

Contributing Copy Chapter

Feedback, ideas, and bug reports Copy Section

If you found a bug, have feedback about our Octicon Library, or an idea on how to improve it, please open a new issue in this repo using the appropriate issue template.

Request an Icon Review (GitHub staff only) Copy Section

To request an icon review for inclusion in the Octicons Library, open the github/primer issue template chooser and select Icon request.

Adding or updating an icon Copy Section

Read through our contributing guide if you want to add or update icons.

License Copy Chapter

(c) GitHub, Inc.

When using the GitHub logos, be sure to follow the GitHub logo guidelines.

Code License: MIT
Applies to all other files

Overview (`.changeset/README.md`) Copy Section

Changesets

Hello and welcome! This folder has been automatically generated by @changesets/cli, a build tool that works
with multi-package repos, or single-package repos to help you version and publish your code. You can
find the full documentation for it in our repository

We have a quick list of common questions to get you started engaging with this project in
our documentation

Overview (`lib/octicons-react-symbols/README.md`) Copy Section

@primer/octicons-react-symbols

Optimized React components for rendering Octicons with shared SVG symbols

Getting started Copy Chapter

To install @primer/octicons-react-symbols in your project, you will need to
run the following command using npm:

npm install -S @primer/octicons-react-symbols

Usage Copy Chapter

The @primer/octicons-react-symbols package provides Octicon components that
reference shared SVG symbols instead of re-creating the same SVG markup every
time an icon is rendered. This is useful in apps that render the same icons many
times, because the symbol definition can be shared while each icon renders a
small <svg></svg> reference.

In your project, add the OcticonSymbols component and provide the symbols that
you would like to include.

import {OcticonSymbols, CheckSymbol} from '@primer/octicons-react-symbols'

function RootLayout() {
  return (
    <OcticonSymbols symbols={[CheckSymbol]}>
      <App />
    </OcticonSymbols>
  )
}

Nested OcticonSymbols components only render symbols that have not already
been provided by an ancestor.

Downstream components can render icon references normally:

import {CheckIconReference} from '@primer/octicons-react-symbols'

function Status() {
  return <CheckIconReference />
}

Compatibility names Copy Section

PlaySymbol and PlayIconReference remain supported circled aliases of the TriangleCircle pair. Alias symbols retain their own SVG IDs, so register PlaySymbol when rendering PlayIconReference. Migrate the symbol and reference names together.

The BookmarkFilled and RepoDeleted pairs remain available with deprecation guidance and their original 16px artwork. Their canonical BookmarkFill and RepoDelete pairs provide both natural sizes.

Custom symbols Copy Section

Use createIconReference to create a custom symbol and its matching icon
reference component. Each size includes the SVG definition and metadata used by
the reference component. The definition and id should reference the same SVG
symbol.

import {createIconReference, OcticonSymbols} from '@primer/octicons-react-symbols'

const [StatusSymbol, StatusIconReference] = createIconReference({
  id: 'symbol-status',
  name: 'StatusIconReference',
  sizes: {
    '16': {
      definition: (
        <symbol id="symbol-status-16" viewBox="0 0 16 16">
          <path d="..." />
        </symbol>
      ),
      id: 'symbol-status-16',
      width: 16,
    },
    '24': {
      definition: (
        <symbol id="symbol-status-24" viewBox="0 0 24 24">
          <path d="..." />
        </symbol>
      ),
      id: 'symbol-status-24',
      width: 24,
    },
  },
})

function RootLayout() {
  return <OcticonSymbols symbols={[StatusSymbol]}>{/* Application content */}</OcticonSymbols>
}

function Status() {
  return <StatusIconReference aria-label="Success" size={24} />
}

Overview (`lib/octicons_gem/README.md`) Copy Section

octicons

Install Copy Chapter

Add this to your Gemfile

gem 'octicons'

Then bundle install.

If using a framework like Rails, please follow the installation instructions in the Primer ViewComponents documentation.

Usage Copy Chapter

require 'octicons'
icon = Octicons::Octicon.new("x")
icon.to_svg
# <svg class="octicon octicon-x" viewBox="0 0 16 16" width="16" height="16" version="1.1" "aria-hidden"="true"><path d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48z"></path></svg>

Documentation Copy Chapter

The Octicon class takes two arguments. The first is the symbol of the icon, and the second is a hash of arguments representing html attributes

`symbol` _(required)_ Copy Section

This is the name of the octicon you want to use. For example alert. Full list of icons

Options Copy Section

• :height - When setting the height to a number, the icon will scale to that size. For example, passing 32, will calculate the width based on the icon's natural size.
• :width - When setting the width to a number, the icon will scale to that size. For example, passing 32, will calculate the width based on the icon's natural size.

If both :width, :height are passed into the options hash, then the icon will be sized exactly at those dimensions.

Attributes Copy Section

Once initialized, you can read a few properties from the icon.

`symbol`

Returns the string of the symbol name

icon = Octicons::Octicon.new("x")
icon.symbol
# "x"

`path`

Path returns the string representation of the path of the icon.

icon = Octicons::Octicon.new("x")
icon.path
# <path d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48z"></path>

`options`

This is a hash of all the options that will be added to the output tag.

icon = Octicons::Octicon.new("x")
icon.options
# {:class=>"octicon octicon-x", :viewBox=>"0 0 12 16", :version=>"1.1", :width=>12, :height=>16, :"aria-hidden"=>"true"}

`width`

Width is the icon's true width. Based on the svg view box width. Note, this doesn't change if you scale it up with size options, it only is the natural width of the icon

`height`

Height is the icon's true height. Based on the svg view box height. Note, this doesn't change if you scale it up with size options, it only is the natural height of the icon

`keywords`

Returns an array of keywords for the icon. The data comes from the data file in lib. Consider contributing more aliases for the icons.

icon = Octicons::Octicon.new("x")
icon.keywords
# ["remove", "close", "delete"]

Methods Copy Section

`to_svg`

Returns a string of the svg tag

icon = Octicons::Octicon.new("x")
icon.to_svg
# <svg class="octicon octicon-x" viewBox="0 0 16 16" width="16" height="16" version="1.1" "aria-hidden"="true"><path d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48z"></path></svg>

Overview (`lib/octicons_helper/README.md`) Copy Section

octicons_helper

This rails helper lets you easily include svg octicons in your rails apps.

Install Copy Chapter

1. Add this to your Gemfile

   rb Copy

   gem 'octicons_helper'

2. Use this tag in your erbs

   rb Copy

   <%= octicon "alert", :height => 32,  :class => "right left", :"aria-label" => "hi" %>

We recommend including the CSS in the @primer/octicons npm module. You can also npm install that package and include build/build.css in your styles.

Overview (`lib/octicons_jekyll/README.md`) Copy Section

jekyll-octicons

The Jekyll liquid tag is a plugin that lets you include octicons in your Jekyll sites.

Install Copy Chapter

1. Add this to your Gemfile

   rb Copy

   gem 'jekyll-octicons'

2. Add this to your jekyll _config.yml

   yml Copy

   plugins:
     - jekyll-octicons

3. Use this tag in your jekyll templates

   text Copy

   {% octicon alert height:32 class:"right left" aria-label:hi %}

We recommend including the CSS in the @primer/octicons npm module. You can also npm install that package and include build/build.css in your styles.

Overview (`lib/octicons_node/README.md`) Copy Section

@primer/octicons

Install Copy Chapter

This package is distributed with npm. After installing npm, you can install @primer/octicons with this command:

npm install @primer/octicons

Usage Copy Chapter

For all the usages, we recommend using the CSS located in build/build.css. This is some simple CSS to normalize the icons and inherit colors.

After installing @primer/octicons you can access the icons like this:

var octicons = require("@primer/octicons")
octicons.alert
// {
//     symbol: 'alert',
//     keywords: ['warning', 'triangle', 'exclamation', 'point'],
//     toSVG: [Function]
//     heights: {
//         16: {
//             width: 16,
//             path: '<path d="M8.865 1.52c-.18-.31-.51-.5-.87-.5s-.69.19-.87.5L.275 13.5c-.18.31-.18.69 0 1 .19.31.52.5.87.5h13.7c.36 0 .69-.19.86-.5.17-.31.18-.69.01-1L8.865 1.52zM8.995 13h-2v-2h2v2zm0-3h-2V6h2v4z"/>',
//             options: {
//                 version: '1.1',
//                 width: '16',
//                 height: '16',
//                 viewBox: '0 0 16 16',
//                 class: 'octicon octicon-alert',
//                 'aria-hidden': 'true'
//             },
//         },
//         24: ...
//     }
// }

There will be a key for every icon, with toSVG and other properties.

Note: alert in the above example can be replaced with any valid icon name. Icons with multi-word names (e.g. arrow-right) cannot be accessed using dot notation (e.g. octicons.alert). Instead, use bracket notation (e.g. octicons['arrow-right']).

`octicons[name].symbol` Copy Section

Returns the string of the symbol name, same as the key for that icon.

octicons.x.symbol
// "x"

`octicons[name].keywords` Copy Section

Returns an array of keywords for the icon. The data comes from keywords.json. Consider contributing more search terms for the icons.

octicons.x.keywords
// ["remove", "close", "delete"]

Compatibility names Copy Section

An optional aliasOf property identifies an icon's canonical name. play remains a supported alias of triangle-circle, while bookmark-filled and repo-deleted also carry deprecated: true. Aliases retain their names, CSS classes, natural drawings, and published SVG paths.

octicons.play.aliasOf
// "triangle-circle"

const canonicalIcons = Object.values(octicons).filter(icon => !icon.aliasOf)

The published build/data.json contains the same alias metadata and keeps legacy keys. Filter aliases only when listing canonical icons, not when resolving names used by existing callers.

`octicons[name].heights` Copy Section

Each icon can have multiple SVGs that are designed for different sizes. The heights property allows you to access all the SVGs for an icon using the natural height of the SVG.

octicons.x.heights
// {
//     16: {
//         width: 16,
//         path: '<path d="..."/>',
//         options: {
//             version: '1.1',
//             width: '16',
//             height: '16',
//             viewBox: '0 0 16 16',
//             class: 'octicon octicon-alert',
//             'aria-hidden': 'true'
//         },
//     },
//     24: {
//         width: 24,
//         path: '<path d="..."/>',
//         options: {
//             version: '1.1',
//             width: '24',
//             height: '24',
//             viewBox: '0 0 24 24',
//             class: 'octicon octicon-alert',
//             'aria-hidden': 'true'
//         },
//     },
// }

`octicons[name].heights[height].width` Copy Section

Returns the icon's true width, based on the SVG view box width. Note, this doesn't change if you scale it up with size options, it only is the natural width of the icon.

`octicons[name].heights[height].path` Copy Section

Returns the string representation of the path of the icon.

octicons.x.heights[16].path
// <path d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48z"></path>

`octicons[name].heights[height].options` Copy Section

This is an object of all the attributes that will be added to the output tag.

octicons.x.heights[16].options
// { version: '1.1', width: '12', height: '16', viewBox: '0 0 12 16', class: 'octicon octicon-x', 'aria-hidden': 'true' }

`octicons[name].toSVG()` Copy Section

Returns a string of the <svg> tag.

octicons.x.toSVG()
// <svg version="1.1" width="12" height="16" viewBox="0 0 12 16" class="octicon octicon-x" aria-hidden="true"><path d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48z"/></svg>

The .toSVG() method accepts an optional options object. This is used to add CSS class names, accessibility options, and sizes.

bookmark-fill and repo-delete retain their 24px output without size options. Pass {height: 16} or {width: 16} to select their 16px drawings. Other existing defaults, including play, stay unchanged.

class

Add more CSS classes to the <svg> tag.

octicons.x.toSVG({ "class": "close" })
// <svg version="1.1" width="12" height="16" viewBox="0 0 12 16" class="octicon octicon-x close" aria-hidden="true"><path d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48z"/></svg>

aria-label

Add accessibility aria-label to the icon.

octicons.x.toSVG({ "aria-label": "Close the window" })
// <svg version="1.1" width="12" height="16" viewBox="0 0 12 16" class="octicon octicon-x" aria-label="Close the window" role="img"><path d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48z"/></svg>

width and height

Size the SVG icon larger using width and height independently or together. .toSVG() will automatically choose the best SVG to render based on the width or height passed in.

octicons.x.toSVG({ "width": 45 })
// <svg version="1.1" width="45" height="45" viewBox="0 0 24 24" class="octicon octicon-x" aria-hidden="true"><path d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48z"/></svg>

Overview (`lib/octicons_react/README.md`) Copy Section

@primer/octicons-react

Install Copy Chapter

npm install @primer/octicons-react

Usage Copy Chapter

Icons Copy Section

The @primer/octicons-react module exports individual icons as named
exports. This
allows you to import only the icons that you need without blowing up your
bundle:

import React from 'react'
import {BeakerIcon, ZapIcon} from '@primer/octicons-react'

export default function Icon({boom}) {
  return boom ? <ZapIcon /> : <BeakerIcon />
}

If you were to compile this example with a tool that supports tree-shaking
(such as Webpack, Rollup, or Parcel) the resulting bundle would only include
the "zap" and "beaker" icons.

Vertical alignment Copy Section

By default the octicons have vertical-align: text-bottom; applied as inline
styles. You can change the alignment via the verticalAlign prop, which can be
either middle, text-bottom, text-top, or top.

import {RepoIcon} from '@primer/octicons-react'

export default () => (
  <h1>
    <RepoIcon verticalAlign="middle" /> github/github
  </h1>
)

`aria-label` Copy Section

You have the option of adding accessibility information to the icon with the
aria-label attribute via the aria-label prop.

// Example usage
import {PlusIcon} from '@primer/octicons-react'

export default () => (
  <button>
    <PlusIcon aria-label="Add new item" /> New
  </button>
)

`aria-labelledby` Copy Section

You have the option of adding accessibility information to the icon with the
aria-labelledby attribute via the aria-labelledby prop. Using aria-labelledby referencing the id values of the title element provides the accessible name.

// Example usage
import {PlusIcon} from '@primer/octicons-react'

export default () => (
  <button>
    <PlusIcon aria-labelledby="title" title="Add new item" /> New
  </button>
)

`title` Copy Section

You have the option of adding accessibility information to the icon with the
title attribute via the title prop.

`id` Copy Section

You have the option of adding information to the icon with the
id attribute via the id prop.

// Example usage
import {PlusIcon} from '@primer/octicons-react'

export default () => (
  <button>
    <PlusIcon id="unique-plus-icon" /> New
  </button>
)

`tabIndex` Copy Section

You can add the tabindex attribute to an SVG element via the tabIndex prop if the SVG element is intended to be interactive.
tabIndex prop also controls the focusable attribute of the SVG element which is defined by SVG Tiny 1.2 and only implemented in
Internet Explorer and Microsoft Edge.

If there is no tabIndex prop is present (default behavior), it will set the focusable attribute to false. This is helpful
for preventing the decorative SVG from being announced by some specialized assistive technology browsing modes which can get delayed
while trying to parse the SVG markup.

// Example usage
import {PlusIcon} from '@primer/octicons-react'
export default () => (
  <PlusIcon aria-label="Interactive Plus Icon" tabIndex={0} /> New Item
)

Sizes Copy Section

The size prop takes small, medium, and large values that can be used to
render octicons at standard sizes:

// Example usage
import {LogoGithubIcon} from '@primer/octicons-react'

export default () => (
  <h1>
    <a href="https://github.com">
      <LogoGithubIcon size="large" aria-label="GitHub" />
    </a>
  </h1>
)

Fill Copy Section

The fill prop takes a string value that can be used to set the color of the icon.
By default, fill is set to currentColor.

// Example usage
import {LogoGithub} from '@primer/octicons-react'
export default () => (
  <h1>
    <a href="https://github.com">
      <LogoGithubIcon fill="#f00" />
    </a>
  </h1>
)

Overview (`lib/octicons_styled/README.md`) Copy Section

@primer/styled-octicons

The @primer/styled-octicons package wraps icon components from @primer/octicons-react with system props, making them easier to style in projects that use styled system—like Primer React.

Install Copy Chapter

npm install @primer/styled-octicons

Usage Copy Chapter

@primer/styled-octicons exports each icons as a named export. This allows you to import only the icons you need:

import {AlertIcon} from '@primer/styled-octicons'

export () => (
  <AlertIcon color="red.6" mr={2} />
)

System props Copy Chapter

All icon components in @primer/styled-octicons get color and space system props as well as the sx prop. Read the Primer React System Props documentation for a full list of available props.

Props Copy Chapter

In addition to system props, icon components in @primer/styled-octicons accept the same props as components in @primer/octicons-react:

Add Octicon Checklist (`docs/add-octicon-checklist.md`) Copy Section

Add an octicon

Use this checklist to add a new/updated octicon to the Figma library and the Octicons package. Read the contributing guidelines for more information on the entire contribution process.

Figma Copy Chapter

• Remove white background from icon frame
• Outline all strokes of vector shape
• Union shapes
• Merge/flatten vector (cmd+e)
• Remove any unused points
• Rename vector layer "Icon"
• Vector layer color set to text/primary
• Name each icon frame with the canonical icon name
  • Note: Octicon names should be written lower case and use - to separate descriptors
  • Note: Follow established family prefixes, such as issue-* and git-pull-request-*
  • Note: Use the exact same base name for every natural size
  • Note: The 16px component uses the bare name; other sizes add one numeric suffix, such as issue-opened-24
• Check the Figma library and published package before reusing a name
  • Note: The same name must identify the same glyph; different artwork needs a distinct name
• If renaming, rename the existing components in place to preserve their node identities
• Copy/paste into Octicons library file
• Convert the icons into components
• Place each component in the matching category frame on its size page
• Set constraints of vectors to Scale/Scale
  • Note: If adding multiple icons, use the "All Constraints" plugin for bulk editing
• Add keywords to icon component
  • Note: All keywords begin with the search flag icon:
  • Note: Keywords should describe other metaphors that the icon can represent when searching
  • Example: The bookmark icon's keywords are "icon: favorite, save, bookmark"

Octicons package Copy Chapter

• Compare the glyph with any existing published icon of the same name; a matching name alone does not establish compatibility
• Use the Octicons Push plugin to create a pull request from Figma
• Confirm exported filenames use the canonical base name and exactly one size suffix
• Confirm every intended natural size is present and document intentional single-size coverage
• Add or update the canonical name in keywords.json
• For a rename, preserve the existing Figma component identity and define the old package name in icon-metadata.json
• Update the React public API snapshot for added or renamed exports
• Add one user-focused changeset for the icon change and select every affected package
  • Note: For a new icon, select minor for @primer/octicons, @primer/octicons-react, @primer/octicons-react-symbols, and @primer/styled-octicons
  • Note: @primer/octicons-react-symbols has an independent 0.x version, so it must be selected explicitly
  • Note: Confirm that the changeset bot adds the linked octicons_gem, octicons_helper, and jekyll-octicons releases
  • Note: Do not add a separate changeset for generated files or snapshot updates
• Open created pull request in the browser and add details
  • Pull request should include:
    • Use case and relevant timeline
    • Canonical names and intended natural sizes
    • Screenshot with descriptive alt text
    • Link to icon request issue for tracking
    • Direct Figma component link for each natural size
    • Compatibility behavior or intentional single-size coverage
• Request reviewers
  • Original requestor (from issue)
  • Member of octicons team
• Submit pull request

Automated monitoring Copy Chapter

The weekly Primer Docs figma-categories and figma-node-map workflows report suspected cross-size naming drift, missing Figma categories or component matches, and duplicate Figma component names.

These workflows provide monitoring after publication. They do not block the Octicons pull request, compare artwork between natural sizes, or prove Figma and npm SVG path parity. Complete every applicable check above before merging.

--- METRICS ---

• Files Extracted: 10
• Estimated Token Budget: ~7712 tokens
• Canonical Reference: https://codewiki.google/github.com/primer/octicons