# Octicons gem
[](https://rubygems.org/gems/octicons)
[](https://travis-ci.org/primer/octicons_gem)
> Octicons gem to distribute octicons svg
## Install
Add this to your `Gemfile`
```rb
gem 'octicons'
```
Then `bundle install`.
## 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][octicons-docs]
#### 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 octicons repository](https://github.com/primer/octicons/blob/master/lib/keywords.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
#
```
##### `to_svg_use`
Returns a string of the svg tag
```rb
icon = Octicons::Octicon.new("x")
icon.to_svg_use
#
```
##### `sprite_sheet`
The Octicons class has a method that will output the svg sprite sheet that you can inline in your app.
```rb
Octicons.sprite_sheet
#
```
## Publishing
If you have access to publish this repository, these are the steps to publishing. If you need access, contact [#design-systems](https://github.slack.com/archives/design-systems).
**Before publishing** This repository relies on the data from [octicons][]. To update to the most recent version, you'll need to run `npm run update`
1. Update the [CHANGELOG.md](./CHANGELOG.md) with relevant version number and any updates made to the repository.
2. Update the version in [version.rb](https://github.com/primer/octicons_gem/blob/master/lib/octicons/version.rb) using the relevant version. The versioning is [semver](http://semver.org/), so version appropriately based on what has changed.
3. `npm version ` Use the same version that you added in step 2.
4. `npm run ship` This will build the gem and publish it to rubygems.
5. `git push && git push --tags` Push all these changes to origin.
## License
(c) 2012-2016 GitHub, Inc.
When using the GitHub logos, be sure to follow the [GitHub logo guidelines](https://github.com/logos).
_Font License:_ [SIL OFL 1.1](http://scripts.sil.org/OFL)
Applies to all font files and SVG files
_Code License:_ [MIT](./LICENSE)
Applies to all other files
[octicons]: https://github.com/primer/octicons
[octicons-docs]: https://octicons.github.com/