1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
|
---
stage: none
group: unassigned
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
---
# Icons and SVG Illustrations
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 is managed as a dependency with yarn. You can browse all available
[icons and illustrations](https://gitlab-org.gitlab.io/gitlab-svgs). To upgrade
to a new version run `yarn upgrade @gitlab/svgs`.
## Icons
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`.
### Usage in HAML/Rails
To use a sprite Icon in HAML or Rails we use a specific helper function:
```ruby
sprite_icon(icon_name, size: nil, css_class: '')
```
- **`icon_name`**: Use the `icon_name` for the SVG sprite in the list of
([GitLab SVGs](https://gitlab-org.gitlab.io/gitlab-svgs)).
- **`size` (optional)**: Use one of the following sizes : 16, 24, 32, 48, 72 (this
is translated into a `s16` class)
- **`css_class` (optional)**: If you want to add additional CSS classes.
**Example**
```haml
= sprite_icon('issues', size: 72, css_class: 'icon-danger')
```
**Output from example above**
```html
<svg class="s72 icon-danger">
<use xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="/assets/icons.svg#issues"></use>
</svg>
```
### Usage in Vue
[GitLab UI](https://gitlab-org.gitlab.io/gitlab-ui/), our components library, provides a component to display sprite icons.
Sample usage :
```html
<script>
import { GlIcon } from "@gitlab/ui";
export default {
components: {
GlIcon,
},
};
<script>
<template>
<gl-icon
name="issues"
:size="24"
class="class-name"
/>
</template>
```
- **name**: Name of the icon of the SVG sprite, as listed in the
([GitLab SVG Previewer](https://gitlab-org.gitlab.io/gitlab-svgs)).
- **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)
- **class (optional)**: Additional CSS classes to add to the SVG tag.
### Usage in HTML/JS
Please use the following function inside JS to render an icon:
`gl.utils.spriteIcon(iconName)`
## Loading icon
### Usage in HAML/Rails
To insert a loading spinner in HAML or Rails use the `gl_loading_icon` helper:
```haml
= gl_loading_icon
```
You can include one or more of the following properties with the `gl_loading_icon` helper, as demonstrated
by the examples that follow:
- `inline` (optional): uses in an inline element if `true`, otherwise, a block element (default), with the spinner centered.
- `color` (optional): either `dark` (default) or `light`.
- `size` (optional): either `sm` (default), `md`, `lg`, or `xl`.
- `css_class` (optional): defaults to nothing, but can be used for utility classes to fine-tune alignment or spacing.
**Example 1:**
The following HAML expression generates a loading icon's markup and
centers the icon.
```haml
= gl_loading_icon
```
**Example 2:**
The following HAML expression generates an inline loading icon's markup
with a custom size. It also appends a margin utility class.
```haml
= gl_loading_icon(inline: true, size: 'lg', css_class: 'gl-mr-2')
```
### Usage in Vue
The [GitLab UI](https://gitlab-org.gitlab.io/gitlab-ui/) components library provides a
`GlLoadingIcon` component. See the component's
[storybook](https://gitlab-org.gitlab.io/gitlab-ui/?path=/story/base-loading-icon--default)
for more information about its usage.
**Example:**
The following code snippet demonstrates how to use `GlLoadingIcon` in
a Vue component.
```html
<script>
import { GlLoadingIcon } from "@gitlab/ui";
export default {
components: {
GlLoadingIcon,
},
};
<script>
<template>
<gl-loading-icon inline />
</template>
```
## SVG Illustrations
From now on, use `img` tags to display any SVG based illustrations with either `image_tag` or `image_path` helpers.
Using the class `svg-content` around it ensures nice rendering.
### Usage in HAML/Rails
**Example**
```haml
.svg-content
= image_tag 'illustrations/merge_requests.svg'
```
### Usage in Vue
To use an SVG illustrations in a template provide the path as a property and display it through a standard `img` tag.
Component:
```html
<script>
export default {
props: {
svgIllustrationPath: {
type: String,
required: true,
},
},
};
<script>
<template>
<img :src="svgIllustrationPath" />
</template>
```
### Minimize SVGs
When you develop or export a new SVG illustration, minimize it with an [SVGO](https://github.com/svg/svgo) powered tool, like
[SVGOMG](https://jakearchibald.github.io/svgomg/), to save space. Illustrations
added to [GitLab SVG](https://gitlab.com/gitlab-org/gitlab-svgs) are automatically
minimized, so no manual action is needed.
|
