Charts

Charts help users quickly digest, visualize and see trends in their data.

Overview

Our charts are built with resources from the Apache ECharts Open Source Library. Charts should be:

• Simple to understand, and easy to interact with.
• Have a consistent visual appearance, and be accessible on all screen sizes.

General guidelines

When creating and utilizing charts, consider the following:

• Use chart titles, category and value labels as necessary to clarify the content being shown, with units in parentheses, if required. Note that units aren't always necessary, for example, in the case of counts.
• If there is more than one data series being displayed, add a legend to differentiate them.
• We have two legend types: default and tabular. The default legend option works best for simple charts. If a chart has many series, or if you want to display multiple values for a series (for example, average, median, and maximum), use the tabular chart legend for better readability.
• In legends, any text after the series name is optional. Use this space to add complementary information as needed, such as total or average values.
• Line and area charts use the series label with the rectangular color chip to match the line colors in the chart, while column and heat map charts use the square color chip to match the fill and stroke color of the elements in the visualization. The fill of the chip should match the fill of the column and the border of the chip should match the border of the column.
• Charts follow the data visualization recommendations for color.
• When hovering, detailed information on the data point is shown in a popover.
• Represent gaps in continuous data with a dashed $grey-300 line, and without a data point.

Types

GitLab UI supports column, line, area, bar, scatter, gauge and sparkline charts. In addition, there are other forms of data visualizations available (see, for example, the overview page for information on heat maps, and the single stat page for additional information on the single stat component).

When implementing a chart type that does not already have a GitLab UI component, you can use the Chart component alongside the ECharts options to build your chart.

When choosing a chart type, first consider your data set. If you are hoping to show:

• A comparison of values across categories or across time, consider a column, bar, line or sparkline chart.
• A comparison between groups or to show how a whole is divided into parts, consider an area chart.
• A distribution of values or the relationship between them, consider a scatter chart.
• A value within a given range, consider a gauge chart.
• The composition of elements within the data set, consider a grouped or stacked column chart.

Chart variations

While most charts only have a single x and y axis, two y-axis charts may occasionally be used; for example, when showing data sets at different orders of magnitude (for example, issues closed, 10; issues opened, 10; total issues 1,000). In this instance, the second y-axis shows how the two data sets are related while ensuring the visualisation at both orders of magnitude is still usable and parsable.

Column charts

Column charts are the default chart type, and they are used to compare values across categories. The categories are usually presented on the x-axis, with the values on the y-axis. Column charts are favored over pie charts because they more clearly communicate data.

The bars on a column chart are presented vertically rather than horizontally, and they can be stacked.

Grouped and stacked column charts

It may sometimes be necessary to stack values in a column or to have groups of columns within your chart, for example when there are two dimensions of data (one nested within another) moving across time. Stacked columns can be either symmetric or asymmetric, meaning the number of stacks may or may not be equal across groups.

The presentation property allows you to change between a stacked and tiled presentation style. It is only setup to accept stacked or tiled as values, the default value is stacked.

The stacked presentation allows to view multiple series of the same stack as a single column, while tiled presents the information in multiple columns for each series of a stack.

groupBy is a property that defines how the data is going to be grouped by for each of the series that the data property provides. For example if the data property has a total of 3 series, with 7 elements each, groupBy could use a 7 element array to show 7 stacked bars or 7 groups of bars depending on the preference set by the presentation property.

Color in stacked and grouped charts

When utilizing stacked and grouped charts, you may choose not to follow the standard color sequencing patterns when doing so provides an extra indicator that items in different groups are related. In addition, graded transparency may help to highlight differences in stacked variables while still differentiating stacks from groups in your chart.

Specific colors may be used when values in a chart have certain colors associated with them in the product; for example, merge request state or vulnerability status. Specific colors should, however, be used sparingly in favor of following the more general color guidelines for data visualizations.

Using grouped and stacked column charts together

When there are three dimensions of data you want to display, it's also possible to group and stack columns in the same chart. If, for example, you want to display all merged MRs in one column, open and closed MRs together in a second column, and show both of these dimensions on the same chart, over time, you could display:

• Merged MRs in one column.
• Open and closed MRs in a separate, stacked column.
• Both columns of data across time (on the x-axis).

Line charts

Line charts are used to display continuous data.

They are useful when you are looking to identify trends or to see larger patterns in your data, and to see how your data changes over time.

Area charts

Area charts are used to represent "cumulated totals using numbers or percentages."

In instances where you want to see both the overall trend and the percent contribution, it is preferable to use a line chart rather than an area chart. It can be very difficult for our eyes to correctly assess the width of areas and how it trends.

Bar charts

Bar charts are a variation of column charts, where the columns are horizontal rather than vertical. It can be used for the same purposes as column charts, which is to compare values across categories.

Scatter charts

Scatter charts give a sense of the distribution and relative size of values.

Gauge charts

Gauge charts highlight the current value within the range of possible values for the metric.

Some layout problems can be encountered with this component. Specifically, when the gauge chart's axis labels or detail text have larger widths, they can overlap with the chart elements.

Also, when the containing element of the gauge chart has either of a small calculated width and height, its axis width could become bulkier in relation to other chart elements. This is because at this time eCharts only allows for setting the axis line width in absolute units.

This issue is to be addressed by https://gitlab.com/gitlab-org/gitlab-ui/-/issues/916.

Sparkline charts

Sparkline charts give a quick indication of trend and a summary of the current value. They are particularly useful when space is limited.

Heatmaps

Note This component uses <gl-legend>, which should allow a user to click on any data point(s) in the legend and make the corresponding data point(s) on the chart rendered disappear. See area chart for an example For this particular chart, there is a known issue with the functionality of the legend, where clicking on it does nothing.

Interaction

Chart popovers

By hovering over specific data points on charts, users will see a popover. The popovers for charts help provide users with more detailed information about both the values being hovered on and their corresponding positions on the x and y axes. The data displayed in the chart popovers is as follows:

• Popover header: x-axis value (x-axis title)
• Popover body: y-axis title, value

Hovering over any of the charts on this page reveals a visual example of how popover content is structured in charts. Placement is set to the right by default to avoid obstructing y-axis data but can be adjusted if doing so would make the chart easier to read. The popover placement should dynamically shift depending on the selected element and space available in the chart.

Text wrapping in chart popovers

The max-width of chart popovers is 512px, with long chart values wrapping rather than truncating. When chart values in popovers wrap, break the word into two lines without using a hyphen.

Chart legends

Chart data can be toggled on and off by clicking its related item in the legend.

Disabling Legends

By default, to prevent the chart from disappearing, all legends can't be toggled off – the last active legend will be disabled. To manually disable a legend, pass it the disabled property in seriesInfo:

seriesInfo = [
  {
    name: 'Example Legend',
    color: 'blue',
    disabled: true,
    type: 'line',
  },
];

More options menu

A "more options" menu (vertical ellipses) can be used in the top righthand corner of charts. This provides users with access to additional chart functionality (such as copying chart embed code) which isn't directly displayed on or near the chart.

Series label

Displays chart data series name as a label for chart legend, tooltip, etc.

Tooltip

Uses GitLab UI's popover component in lieu of echart's tooltip.

Zoom bar

ECharts has a default mechanism for zooming on charts. A zoom bar gives users more control over how much data is displayed at any one time, and gives them the ability to dig into issues they are observing at a more granular level.

The zoom bar is not added to all charts by default and shouldn't be used in cases where the chart neatly fits its container. However, in instances where the chart would otherwise overflow its container or where there is a large amount of data for users to explore, the zoom bar should be introduced.

Design specifications

Color, spacing, dimension, and layout specific information pertaining to this component can be viewed using the following links:

Pajamas UI Kit →

Line chart in Pajamas UI Kit →

Code reference

ECharts Wrapper

The chart component is a Vue component wrapper around Apache ECharts. The chart component accepts width and height props in order to allow the user to make it responsive.

EChart Lifecycle

This component emits the following events during the ECharts lifecycle:

• created: emitted after calling echarts.init
• updated: emitted after calling echarts.setOption

In all cases, the event payload is the echart instance.