171 lines
5.7 KiB
Plaintext
Executable File
171 lines
5.7 KiB
Plaintext
Executable File
---
|
|
title: JavaScript
|
|
status: Stable
|
|
source: 'https://github.com/primer/octicons/tree/master/lib/octicons_node'
|
|
---
|
|
|
|
[](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: '<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`](#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 the [data file in lib](../data.json). Consider contributing more aliases for the icons.
|
|
|
|
```js
|
|
octicons.x.keywords
|
|
// ["remove", "close", "delete"]
|
|
```
|
|
|
|
### `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: '<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`
|
|
|
|
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
|
|
// <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`
|
|
|
|
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 `<svg>` tag.
|
|
|
|
```js
|
|
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.
|
|
|
|
```js
|
|
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.
|
|
|
|
```js
|
|
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. `.toSVG()` will automatically choose the best SVG to render based on the width or height passed in.
|
|
|
|
```js
|
|
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>
|
|
```
|
|
|
|
[primer]: https://github.com/primer/primer
|
|
[docs]: http://primercss.io/
|
|
[npm]: https://www.npmjs.com/
|
|
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
|
|
[sass]: http://sass-lang.com/
|