Dashboard panel

Structure

1. Container: Wraps the dashboard panel content.
2. Title icon (optional): In some cases the dashboard panel title can be prefixed with an icon (for example, a severity type or runner status).
3. Title: Concisely describes the dashboard panel.
4. Info icon (optional): Triggers a popover to add additional context about the data.
5. Badge (optional): Communicates additional information (for example, Beta or Experiment).
6. Configuration menu: Contains dashboard panel settings and actions.
7. Subtitle (optional): Specify the data time range, refresh frequency, and any exclusions (for example, Last 30 days, excludes weekends).
8. Filter (optional): Adds refinement options to further narrow data beyond the page-level context.
9. Visualization: A graphical representation of query results (for example, a chart, a table, or a list).
10. Resize: For user-customizable dashboards, dashboard panels can be resized and repositioned on a dashboard using drag-and-drop.

Guidelines

When to use

• For a standardized container for individual results in a dashboard, report, or other analytics-focused interface.
• To wrap a single visualization of query results, such as a chart, markdown, single stat, or table.
• Easy integration with GlDashboardLayout.

When not to use

• For simple content grouping without data visualization, consider using a card instead.
• For content that doesn't require standardized dashboard layout integration.
• For interactive elements that aren't related to data visualization or analytics.

Titles

Keep to one line using sentence fragments:

Avoid punctuation except full stops for complete sentences:

Avoid conversational tone:

Considerations

Maintain simplicity

Limit each dashboard panel to one visualization for better scalability and easier configuration. Multiple visualizations in a single dashboard panel creates cognitive overload, making it harder for a user to quickly extract insights. A single-purpose dashboard panel is easier to understand at a glance, reduces decision fatigue, and allows a user to build their mental model more effectively. From a technical perspective, isolated components are easier to maintain, debug, and update without affecting other visualizations. An isolated component also scales better across different screen sizes and can be more easily rearranged or reused in a different dashboard context.

Limit filters

Keep dashboard panel-level filter options minimal. Too many filters create analysis paralysis and increases the likelihood of a user creating a misleading or incorrect data view. Minimal filters reduce cognitive load and help maintain focus on the most important data dimensions. This also improves dashboard performance, since fewer filter combinations result in more predictable query patterns and better caching opportunities. Additionally, minimal dashboard panel-level filter options ensure consistency across user experiences and reduce the risk of a user getting lost in edge-case filter combinations that may not provide meaningful insights.

Code reference

GlDashboardPanel

The GlDashboardPanel component is a container that can be used in dashboards or other analytics-focused pages. While not opinionated about its contents, it's designed as a container for a single query result visualization. It wraps its content with standardized styling, loading states, actions, and metadata. It does not manage data states and fetching, or handle filter state management.

Loading states

A dashboard panel provides built-in loading state management. When content is loading:

• Set the loading prop to true to show a loading spinner.
• Use loadingDelayed and loadingDelayedText for long-running operations.
• The dashboard panel handles the visual loading state while your content handles the actual data loading.

Filters

The component provides a #filters slot for you to render your filters within the dashboard panel layout. It's up to the consumer to manage the state of filters.

Basic implementation

<script> import { GlDashboardPanel } from '@gitlab/ui'; import MyVisualization from './my_visualization.vue'; export default { components: { GlDashboardPanel, MyVisualization, }, data() { return { isLoading: false, }; }, }; </script> <template> <gl-dashboard-panel title="My Content Title" :loading="isLoading" > <template #body> <my-visualization /> </template> </gl-dashboard-panel> </template>