2018-05-27 19:21:12 +00:00
# Icons and SVG Illustrations
2017-09-22 08:39:47 +00:00
2020-04-21 15:21:10 +00:00
We manage our own Icon and Illustration library in the [`gitlab-svgs` ](https://gitlab.com/gitlab-org/gitlab-svgs ) repository.
This repository is published on [npm ](https://www.npmjs.com/package/@gitlab/svgs ) and managed as a dependency via yarn.
You can browse all available Icons and Illustrations [here ](https://gitlab-org.gitlab.io/gitlab-svgs ).
2018-10-31 11:35:33 +00:00
To upgrade to a new version run `yarn upgrade @gitlab/svgs` .
2017-09-22 08:39:47 +00:00
2018-05-27 19:21:12 +00:00
## Icons
2017-09-22 08:39:47 +00:00
2018-05-27 19:21:12 +00:00
We are using SVG Icons in GitLab with a SVG Sprite.
This means the icons are only loaded once, and are referenced through an ID.
The sprite SVG is located under `/assets/icons.svg` .
Our goal is to replace one by one all inline SVG Icons (as those currently bloat the HTML) and also all Font Awesome icons.
2017-09-22 08:39:47 +00:00
2018-05-27 19:21:12 +00:00
### Usage in HAML/Rails
2017-09-22 08:39:47 +00:00
2018-05-27 19:21:12 +00:00
To use a sprite Icon in HAML or Rails we use a specific helper function :
2017-11-03 08:44:00 +00:00
2018-05-27 19:21:12 +00:00
```ruby
sprite_icon(icon_name, size: nil, css_class: '')
```
2017-11-03 08:44:00 +00:00
2019-07-18 01:15:58 +00:00
- **icon_name** Use the icon_name that you can find in the SVG Sprite
2020-04-21 15:21:10 +00:00
([Overview is available here](https://gitlab-org.gitlab.io/gitlab-svgs)).
2019-07-18 01:15:58 +00:00
- **size (optional)** Use one of the following sizes : 16, 24, 32, 48, 72 (this will be translated into a `s16` class)
- **css_class (optional)** If you want to add additional css classes
2017-09-22 08:39:47 +00:00
2017-11-03 08:44:00 +00:00
**Example**
2017-09-22 08:39:47 +00:00
2018-05-27 19:21:12 +00:00
```haml
= sprite_icon('issues', size: 72, css_class: 'icon-danger')
```
2017-09-22 08:39:47 +00:00
**Output from example above**
2018-05-27 19:21:12 +00:00
```html
< svg class = "s72 icon-danger" >
< use xmlns:xlink = "http://www.w3.org/1999/xlink" xlink:href = "/assets/icons.svg#issues" > < / use >
< / svg >
```
2017-09-22 08:39:47 +00:00
2017-11-03 08:44:00 +00:00
### Usage in Vue
2020-04-21 15:21:10 +00:00
[GitLab UI ](https://gitlab-org.gitlab.io/gitlab-ui/ ), our components library, provides a component to display sprite icons.
2017-11-03 08:44:00 +00:00
Sample usage :
2020-02-17 15:09:01 +00:00
```html
2018-05-27 19:21:12 +00:00
< script >
2020-02-17 15:09:01 +00:00
import { GlIcon } from "@gitlab/ui";
2018-05-27 19:21:12 +00:00
export default {
components: {
2020-02-17 15:09:01 +00:00
GlIcon,
2018-05-27 19:21:12 +00:00
},
};
< script >
2020-02-17 15:09:01 +00:00
2018-05-27 19:21:12 +00:00
< template >
2020-02-17 15:09:01 +00:00
< gl-icon
2018-05-27 19:21:12 +00:00
name="issues"
2019-10-02 21:06:22 +00:00
:size="24"
2018-05-27 19:21:12 +00:00
/>
< / template >
```
2020-04-21 15:21:10 +00:00
- **name** Name of the Icon in the SVG Sprite ([Overview is available here](https://gitlab-org.gitlab.io/gitlab-svgs)).
2019-07-18 01:15:58 +00:00
- **size (optional)** Number value for the size which is then mapped to a specific CSS class
(Available Sizes: 8, 12, 16, 18, 24, 32, 48, 72 are mapped to `sXX` css classes)
- **css-classes (optional)** Additional CSS Classes to add to the svg tag.
2017-11-03 08:44:00 +00:00
2017-09-22 08:39:47 +00:00
### Usage in HTML/JS
2018-05-27 19:21:12 +00:00
Please use the following function inside JS to render an icon:
2017-09-22 08:39:47 +00:00
`gl.utils.spriteIcon(iconName)`
2018-05-27 19:21:12 +00:00
## SVG Illustrations
2017-09-22 08:39:47 +00:00
2018-05-27 19:21:12 +00:00
Please use from now on for any SVG based illustrations simple `img` tags to show an illustration by simply using either `image_tag` or `image_path` helpers.
Please use the class `svg-content` around it to ensure nice rendering.
2017-09-22 08:39:47 +00:00
2018-05-27 19:21:12 +00:00
### Usage in HAML/Rails
2017-09-22 08:39:47 +00:00
2018-05-27 19:21:12 +00:00
**Example**
2017-09-22 08:39:47 +00:00
2018-05-27 19:21:12 +00:00
```haml
.svg-content
= image_tag 'illustrations/merge_requests.svg'
```
2017-09-22 08:39:47 +00:00
2018-05-27 19:21:12 +00:00
### Usage in Vue
2017-09-22 08:39:47 +00:00
2018-05-27 19:21:12 +00:00
To use an SVG illustrations in a template provide the path as a property and display it through a standard img tag.
Component:
2020-02-17 15:09:01 +00:00
```html
2018-05-27 19:21:12 +00:00
< script >
export default {
props: {
svgIllustrationPath: {
type: String,
required: true,
},
},
};
< script >
2020-02-17 15:09:01 +00:00
2018-05-27 19:21:12 +00:00
< template >
< img :src = "svgIllustrationPath" / >
< / template >
```