Octicons are a set of SVG icons built by GitHub for GitHub.
## Libraries
This repository contains several libraries. Each of them is in the `lib/` folder and gives access to Octicons on a different platform/language.
### JavaScript
The octicons node.js library is the main JavaScript library. With [a JavaScript API](/lib/octicons_node/README.md) that can be used in a variety of applications.
| Package | Version |
| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| **[@primer/octicons](/lib/octicons_node)** Node.js package with JavaScript API | [](https://www.npmjs.org/package/@primer/octicons) |
| **[@primer/octicons-react](/lib/octicons_react)** React Octicons components | [](https://www.npmjs.org/package/@primer/octicons-react) |
| **[@primer/styled-octicons](/lib/octicons_styled)** React Octicons components with Styled System props | [](https://www.npmjs.org/package/@primer/styled-octicons) |
### Ruby
| Package | Version |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **[octicons](/lib/octicons_gem)** Ruby gem with Ruby API | [](https://rubygems.org/gems/octicons) |
| [octicons_helper](/lib/octicons_helper) Rails helper for using octicons | [](https://rubygems.org/gems/octicons_helper) |
| [jekyll-octicons](/lib/octicons_jekyll) Jekyll plugin for using octicons | [](https://rubygems.org/gems/jekyll-octicons) |
## Icon names and compatibility
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.
| Canonical name | Compatibility name | Preserved behavior |
| ----------------- | ------------------------------ | --------------------------------------------------------------------------- |
| `bookmark-fill` | `bookmark-filled` (deprecated) | The old name retains its 16px drawing at every display size. |
| `repo-delete` | `repo-deleted` (deprecated) | The old name retains its 16px drawing at every display size. |
| `triangle-circle` | `play` (supported) | The old name retains both original circled drawings, not the bare triangle. |
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
### Feedback, ideas, and bug reports
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](https://github.com/primer/octicons/issues/new/choose).
### Request an Icon Review (GitHub staff only)
To request an icon review for inclusion in the Octicons Library, open the [github/primer issue template chooser](https://github.com/github/primer/issues/new/choose) and select **Icon request**.
### Adding or updating an icon
Read through our [contributing guide](./CONTRIBUTING.md#adding-or-updating-icons) if you want to add or update icons.
## License
(c) GitHub, Inc.
When using the GitHub logos, be sure to follow the [GitHub logo guidelines](https://github.com/logos).
_Code License:_ [MIT](./LICENSE)
Applies to all other files
---
### Overview (`.changeset/README.md`)
# 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](https://github.com/changesets/changesets)
We have a quick list of common questions to get you started engaging with this project in
[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)
---
### Overview (`lib/octicons-react-symbols/README.md`)
# @primer/octicons-react-symbols
> Optimized React components for rendering Octicons with shared SVG symbols
## Getting started
To install `@primer/octicons-react-symbols` in your project, you will need to
run the following command using [npm](https://www.npmjs.com/):
```bash
npm install -S @primer/octicons-react-symbols
```
## Usage
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 `` reference.
In your project, add the `OcticonSymbols` component and provide the symbols that
you would like to include.
```tsx
import {OcticonSymbols, CheckSymbol} from '@primer/octicons-react-symbols'
function RootLayout() {
return (
)
}
```
Nested `OcticonSymbols` components only render symbols that have not already
been provided by an ancestor.
Downstream components can render icon references normally:
```tsx
import {CheckIconReference} from '@primer/octicons-react-symbols'
function Status() {
return
}
```
### Compatibility names
`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
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.
```tsx
import {createIconReference, OcticonSymbols} from '@primer/octicons-react-symbols'
const [StatusSymbol, StatusIconReference] = createIconReference({
id: 'symbol-status',
name: 'StatusIconReference',
sizes: {
'16': {
definition: (
),
id: 'symbol-status-16',
width: 16,
},
'24': {
definition: (
),
id: 'symbol-status-24',
width: 24,
},
},
})
function RootLayout() {
return {/* Application content */}
}
function Status() {
return
}
```
---
### Overview (`lib/octicons_gem/README.md`)
# octicons
[](https://rubygems.org/gems/octicons)
## Install
Add this to your `Gemfile`
```rb
gem 'octicons'
```
Then `bundle install`.
If using a framework like Rails, please follow the [installation instructions](https://primer.style/view-components/#installation) in the [Primer ViewComponents](https://primer.style/view-components) documentation.
## Usage
```rb
require 'octicons'
icon = Octicons::Octicon.new("x")
icon.to_svg
#
```
## Documentation
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)_
This is the name of the octicon you want to use. For example `alert`. [Full list of icons](/)
### Options
* `: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
Once initialized, you can read a few properties from the icon.
#### `symbol`
Returns the string of the symbol name
```rb
icon = Octicons::Octicon.new("x")
icon.symbol
# "x"
```
#### `path`
Path returns the string representation of the path of the icon.
```rb
icon = Octicons::Octicon.new("x")
icon.path
#
```
#### `options`
This is a hash of all the `options` that will be added to the output tag.
```rb
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](../data.json). Consider contributing more aliases for the icons.
```rb
icon = Octicons::Octicon.new("x")
icon.keywords
# ["remove", "close", "delete"]
```
### Methods
#### `to_svg`
Returns a string of the svg tag
```rb
icon = Octicons::Octicon.new("x")
icon.to_svg
#
```
---
### Overview (`lib/octicons_helper/README.md`)
# octicons_helper
[](https://rubygems.org/gems/octicons_helper)
This rails helper lets you easily include svg octicons in your rails apps.
## Install
1. Add this to your `Gemfile`
```rb
gem 'octicons_helper'
```
3. Use this tag in your erbs
```rb
<%= octicon "alert", :height => 32, :class => "right left", :"aria-label" => "hi" %>
```
We recommend including the CSS in the [`@primer/octicons`](/packages/javascript) npm module. You can also npm install that package and include `build/build.css` in your styles.
---
### Overview (`lib/octicons_jekyll/README.md`)
# jekyll-octicons
[](https://rubygems.org/gems/jekyll-octicons)
The Jekyll liquid tag is a plugin that lets you include octicons in your Jekyll sites.
## Install
1. Add this to your `Gemfile`
```rb
gem 'jekyll-octicons'
```
2. Add this to your jekyll `_config.yml`
```yml
plugins:
- jekyll-octicons
```
3. Use this tag in your jekyll templates
```
{% octicon alert height:32 class:"right left" aria-label:hi %}
```
We recommend including the CSS in the [`@primer/octicons`](/packages/javascript) npm module. You can also npm install that package and include `build/build.css` in your styles.
---
### Overview (`lib/octicons_node/README.md`)
# @primer/octicons
[](https://www.npmjs.org/package/@primer/octicons)
## Install
This package is distributed with [npm][npm]. After [installing npm][install-npm], you can install `@primer/octicons` with this command:
```shell
npm install @primer/octicons
```
## Usage
For all the usages, we recommend using the CSS located in [`build/build.css`](https://unpkg.com/@primer/octicons/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:
```js
var octicons = require("@primer/octicons")
octicons.alert
// {
// symbol: 'alert',
// keywords: ['warning', 'triangle', 'exclamation', 'point'],
// toSVG: [Function]
// heights: {
// 16: {
// width: 16,
// path: '',
// 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`](#octiconsnametosvg) 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`
Returns the string of the symbol name, same as the key for that icon.
```js
octicons.x.symbol
// "x"
```
### `octicons[name].keywords`
Returns an array of keywords for the icon. The data comes from [keywords.json](https://github.com/primer/octicons/blob/main/keywords.json). Consider contributing more search terms for the icons.
```js
octicons.x.keywords
// ["remove", "close", "delete"]
```
### Compatibility names
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.
```js
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`
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.
```js
octicons.x.heights
// {
// 16: {
// width: 16,
// path: '',
// options: {
// version: '1.1',
// width: '16',
// height: '16',
// viewBox: '0 0 16 16',
// class: 'octicon octicon-alert',
// 'aria-hidden': 'true'
// },
// },
// 24: {
// width: 24,
// path: '',
// 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`
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`
Returns the string representation of the path of the icon.
```js
octicons.x.heights[16].path
//
```
### `octicons[name].heights[height].options`
This is an object of all the attributes that will be added to the output tag.
```js
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()`
Returns a string of the `
