Icons and SVG Illustrations

We manage our own icon and illustration library in the gitlab-svgs package. This package 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 an 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 an 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

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): used 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 spinner documentation 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

It is discouraged to pass down SVG paths from Rails. Instead of Rails => Haml => Vue we can import SVG illustrations directly in Vue.

To use an SVG illustration in a template import the SVG from @gitlab/svgs. You can find the available SVG paths via the GitLab SVG Previewer.

Below is an example of how to import an SVG illustration and use it with the GlEmptyState component.

Component:

<script>
import { GlEmptyState } from '@gitlab/ui';
// The ?url query string ensures the SVG is imported as a URL instead of an inline SVG
// This is useful for bundle size and optimized loading
import mergeTrainsSvgPath from '@gitlab/svgs/dist/illustrations/train-sm.svg?url';

export default {
  components: {
    GlEmptyState
  },
  mergeTrainsSvgPath,
};
<script>

<template>
  <gl-empty-state
    title="This state is empty"
    description="Empty state description"
    :svg-path="$options.mergeTrainsSvgPath"
  />
</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.