Grafana Product Design Engineering Components

Installation

Add @grafana/components to your project’s dependencies:

$ npm install @grafana/components

or

$ yarn add @grafana/components

To ensure that the necessary providers are present, you should add the following to your App.tsx (or equivalent):

import { getAppEvents } from '@grafana/runtime';
import { useTheme2 } from '@grafana/ui';
import { PortalProvider, ColorMode } from '@grafana/components';

const App = () => {
  return (
    <PortalProvider defaultRoot="grafana-portal-container">
      <ColorMode getAppEvents={getAppEvents} useTheme2={useTheme2}>
        <YourApp />
      </ColorMode>
    </PortalProvider>
  );
};

The dependency on useTheme2 is necessary (for now) to detect the active color mode (light or dark); this dependency will go away in the longer term.

Additionally, to ensure that the stylesheet imported by ColorMode is correctly included in the App bundle, you will need to update your project’s webpack.config.ts configuration for the style-loader loader module:

  {
    test: /\.css$/,
    use: ['style-loader', 'css-loader'],
+   sideEffects: true,
  },

This is to ensure that including stylesheets with @import 'path/to/stylesheet.css'; works correctly and the stylesheets aren’t unintentionally ‘tree-shaken’ out.

Custom Icons

The icons included with @grafana/components are based on Lucide, which provides over 1,800 consistent icons. In addition, there are a smaller number of custom icons available. All custom icons are sourced from src/icons/svg, whereas the Lucide icons are sourced from the lucide-static package.

Since Lucide’s icon design principles state you should design your icon to use stroked paths, should you need to use solid filled shapes in your icon, you will need to make sure it follows the right approach:

• The <path> elements should be devoid of any style attributes or other properties (i.e. only the d property should exist)
• The root level <svg> element should have the fill="solid" attribute property

The latter property is important when running yarn import:icons to ensure the component will render with a solid fill and no stroke. You should also try to follow the icon design principles where possible to keep it consistent with other icons.

...

Publishing

Currently this repo is not configured to automatically publish through CI (the GH action will report as failing). In order to publish a new version, you will need to do so locally using 2FA. First log into npmjs.com using this script:

yarn npm:login

Once this confirms you are logged in, run this script to build and publish the package (you will be prompted to enter a 2FA code again):

yarn build:publish