gitlab-org--gitlab-foss/doc/development/fe_guide/icons.md

stage	group	info
none	unassigned	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 repository. This repository is published on npm, and is managed as a dependency with yarn. You can browse all available icons and illustrations. 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:

sprite_icon(icon_name, size: nil, css_class: '')

• icon_name: Use the icon_name for the SVG sprite in the list of (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

= sprite_icon('issues', size: 72, css_class: 'icon-danger')

Output from example above

<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, our components library, provides a component to display sprite icons.

Sample usage :

<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).
• 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:

= 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.

= 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.

= gl_loading_icon(inline: true, size: 'lg', css_class: 'gl-mr-2')

Usage in Vue

The GitLab UI components library provides a GlLoadingIcon component. See the component's storybook for more information about its usage.

Example:

The following code snippet demonstrates how to use GlLoadingIcon in a Vue component.

<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

.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:

<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 powered tool, like SVGOMG, to save space. Illustrations added to GitLab SVG are automatically minimized, so no manual action is needed.