GitHub Octicons

Octicons are a scalable set of icons handcrafted with <3 by GitHub.

Install

NOTE: The compiled files are located in build/. This directory is located in the published npm package. Which means you can access it when you npm install octicons. You can also build this directory by following the building octicons directions. The files in the lib/ directory are the raw source files and are not compiled or optimized.

npm

This repository is distributed with npm. After installing npm, you can install octicons with this command.

$ npm install octicons --save

Usage

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

Spritesheet

With an SVG sprite icon system you can include the sprite sheet located build/sprite.octicons.svg after you build the icons or from the npm package. There is a demo of how to use the spritesheet in the build/ directory also.

Node

After installing npm install octicons you can access the icons like this.

var octicons = require("octicons")
octicons.alert
// { keywords: [ 'warning', 'triangle', 'exclamation', 'point' ],
//   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"/>',
//   height: '16',
//   width: '16',
//   symbol: 'alert',
//   options:
//    { version: '1.1',
//      width: '16',
//      height: '16',
//      viewBox: '0 0 16 16',
//      class: 'octicon octicon-alert',
//      'aria-hidden': 'true' },
//   toSVG: [Function] }

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

`octicons.alert.symbol`

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

octicons.x.symbol
// "x"

`octicons.person.path`

Returns the string representation of the path of the icon.

octicons.x.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.issue.options`

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

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

`octicons.alert.width`

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.alert.height`

Returns 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 lib/data.json. Consider contributing more aliases for the icons.

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

`octicons.alert.toSVG()`

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 classnames, a11y options, and sizing.

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 & height

Size the SVG icon larger using width & height independently or together.

octicons.x.toSVG({ "width": 45 })
// <svg version="1.1" width="45" height="60" 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>

`octicons.alert.toSVGUse()`

Returns a string of the svg tag with the <use> tag, for use with the spritesheet located in the build/ directory.

octicons.x.toSVGUse()
// <svg version="1.1" width="12" height="16" viewBox="0 0 12 16" class="octicon octicon-x" aria-hidden="true"><use xlink:href="#x" /></svg>

Ruby

If your environment is Ruby on Rails, we have an octicons_helper gem available that renders SVG in your page. The octicons_helper uses the octicons_gem to do the computing and reading of the SVG files.

Jekyll

For jekyll, there's a jekyll-octicons plugin available. This works exactly like the octicons_helper.

Changing, adding, or deleting icons

Open the Sketch document in lib/. Each icon exists as an artboard within our master Sketch document. If you’re adding an icon, duplicate one of the artboards and add your shapes to it. Be sure to give your artboard a name that makes sense.
Once you’re happy with your icon set, choose File > Export…
Choose all the artboards you’d like to export and then press “Export”
Export to lib/svg/

You’ll next need to build your Octicons.

Building Octicons

All the files you need will be in the build/ directory already, but if you’ve made changes to the lib/ directory and need to regenerate, follow these steps:

Open the Octicons directory in Terminal
npm install to install all dependencies for the project.
Run the command npm run build. This will run the grunt task to build the SVGs, placing them in the build/ directory.

Publishing

If you have access to publish this repository, these are the steps to publishing. If you need access, contact #design-systems.

Update the CHANGELOG.md with relevant version number and any updates made to the repository.
npm version <newversion> Run npm version inputing the relevant version type. The versioning is semver, so version appropriately based on what has changed.
npm publish This will publish the new version to npmjs.org
git push && git push --tags Push all these changes to origin.

License

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

SVG License: SIL OFL 1.1
Applies to all SVG files

Code License: MIT
Applies to all other files

cgnkev/octicons