debian-mirror-gitlab/doc/development/fe_guide/icons.md

194 lines
5 KiB
Markdown
Raw Normal View History

2021-01-29 00:20:46 +05:30
---
stage: none
group: unassigned
2021-02-22 17:27:13 +05:30
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
2021-01-29 00:20:46 +05:30
---
2018-11-08 19:23:39 +05:30
# Icons and SVG Illustrations
2018-03-17 18:26:18 +05:30
2021-01-03 14:25:43 +05:30
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`.
2018-03-17 18:26:18 +05:30
2018-11-08 19:23:39 +05:30
## Icons
2018-03-17 18:26:18 +05:30
2018-11-08 19:23:39 +05:30
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
2018-03-17 18:26:18 +05:30
2021-02-22 17:27:13 +05:30
To use a sprite Icon in HAML or Rails we use a specific helper function:
2018-03-17 18:26:18 +05:30
2018-11-08 19:23:39 +05:30
```ruby
sprite_icon(icon_name, size: nil, css_class: '')
```
2018-03-17 18:26:18 +05:30
2021-03-11 19:13:27 +05:30
- **`icon_name`**: Use the `icon_name` for the SVG sprite in the list of
2021-01-03 14:25:43 +05:30
([GitLab SVGs](https://gitlab-org.gitlab.io/gitlab-svgs)).
2021-03-11 19:13:27 +05:30
- **`size` (optional)**: Use one of the following sizes : 16, 24, 32, 48, 72 (this
2021-02-22 17:27:13 +05:30
is translated into a `s16` class)
2021-03-11 19:13:27 +05:30
- **`css_class` (optional)**: If you want to add additional CSS classes.
2018-03-17 18:26:18 +05:30
**Example**
2018-11-08 19:23:39 +05:30
```haml
= sprite_icon('issues', size: 72, css_class: 'icon-danger')
```
2018-03-17 18:26:18 +05:30
**Output from example above**
2018-11-08 19:23:39 +05:30
```html
<svg class="s72 icon-danger">
<use xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="/assets/icons.svg#issues"></use>
</svg>
```
2018-03-17 18:26:18 +05:30
### Usage in Vue
2020-05-24 23:13:21 +05:30
[GitLab UI](https://gitlab-org.gitlab.io/gitlab-ui/), our components library, provides a component to display sprite icons.
2018-03-17 18:26:18 +05:30
Sample usage :
2020-03-13 15:44:24 +05:30
```html
2018-11-08 19:23:39 +05:30
<script>
2020-03-13 15:44:24 +05:30
import { GlIcon } from "@gitlab/ui";
2018-11-08 19:23:39 +05:30
export default {
components: {
2020-03-13 15:44:24 +05:30
GlIcon,
2018-11-08 19:23:39 +05:30
},
};
<script>
2020-03-13 15:44:24 +05:30
2018-11-08 19:23:39 +05:30
<template>
2020-03-13 15:44:24 +05:30
<gl-icon
2018-11-08 19:23:39 +05:30
name="issues"
2019-12-21 20:55:43 +05:30
:size="24"
2020-07-28 23:09:34 +05:30
class="class-name"
2018-11-08 19:23:39 +05:30
/>
</template>
```
2021-01-03 14:25:43 +05:30
- **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.
2018-03-17 18:26:18 +05:30
### Usage in HTML/JS
2018-11-08 19:23:39 +05:30
Please use the following function inside JS to render an icon:
2018-03-17 18:26:18 +05:30
`gl.utils.spriteIcon(iconName)`
2020-10-24 23:57:45 +05:30
## Loading icon
### Usage in HAML/Rails
2022-05-07 20:08:51 +05:30
To insert a loading spinner in HAML or Rails use the `gl_loading_icon` helper:
2020-10-24 23:57:45 +05:30
```haml
2022-05-07 20:08:51 +05:30
= gl_loading_icon
2020-10-24 23:57:45 +05:30
```
2022-05-07 20:08:51 +05:30
You can include one or more of the following properties with the `gl_loading_icon` helper, as demonstrated
2020-10-24 23:57:45 +05:30
by the examples that follow:
2022-05-07 20:08:51 +05:30
- `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`.
2020-10-24 23:57:45 +05:30
- `size` (optional): either `sm` (default), `md`, `lg`, or `xl`.
2022-05-07 20:08:51 +05:30
- `css_class` (optional): defaults to nothing, but can be used for utility classes to fine-tune alignment or spacing.
2020-10-24 23:57:45 +05:30
**Example 1:**
2021-04-29 21:17:54 +05:30
The following HAML expression generates a loading icon's markup and
2022-05-07 20:08:51 +05:30
centers the icon.
2020-10-24 23:57:45 +05:30
```haml
2022-05-07 20:08:51 +05:30
= gl_loading_icon
2020-10-24 23:57:45 +05:30
```
**Example 2:**
2022-05-07 20:08:51 +05:30
The following HAML expression generates an inline loading icon's markup
2020-10-24 23:57:45 +05:30
with a custom size. It also appends a margin utility class.
```haml
2022-05-07 20:08:51 +05:30
= gl_loading_icon(inline: true, size: 'lg', css_class: 'gl-mr-2')
2020-10-24 23:57:45 +05:30
```
### Usage in Vue
The [GitLab UI](https://gitlab-org.gitlab.io/gitlab-ui/) components library provides a
2021-04-29 21:17:54 +05:30
`GlLoadingIcon` component. See the component's
2020-10-24 23:57:45 +05:30
[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>
```
2018-11-08 19:23:39 +05:30
## SVG Illustrations
2018-03-17 18:26:18 +05:30
2021-03-11 19:13:27 +05:30
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.
2018-03-17 18:26:18 +05:30
2018-11-08 19:23:39 +05:30
### Usage in HAML/Rails
2018-03-17 18:26:18 +05:30
2018-11-08 19:23:39 +05:30
**Example**
2018-03-17 18:26:18 +05:30
2018-11-08 19:23:39 +05:30
```haml
.svg-content
= image_tag 'illustrations/merge_requests.svg'
```
2018-03-17 18:26:18 +05:30
2018-11-08 19:23:39 +05:30
### Usage in Vue
2018-03-17 18:26:18 +05:30
2020-06-23 00:09:42 +05:30
To use an SVG illustrations in a template provide the path as a property and display it through a standard `img` tag.
2018-11-08 19:23:39 +05:30
Component:
2020-03-13 15:44:24 +05:30
```html
2018-11-08 19:23:39 +05:30
<script>
export default {
props: {
svgIllustrationPath: {
type: String,
required: true,
},
},
};
<script>
2020-03-13 15:44:24 +05:30
2018-11-08 19:23:39 +05:30
<template>
<img :src="svgIllustrationPath" />
</template>
```
2021-06-08 01:23:25 +05:30
### 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.