UI Components & Theming
Relevant source files
The following files were used as context for generating this wiki page:
The Grafana UI system is a centralized framework designed to ensure visual consistency, accessibility, and developer efficiency across the platform. It relies on a React-based component library (@grafana/ui), a robust theming engine (GrafanaTheme2), and comprehensive style guides that prioritize modern CSS-in-JS patterns over legacy Sass styles.
The system is built to support both internal development and external plugin authors, providing a shared language of design tokens (colors, spacing, typography) and pre-built components.
Architecture and Styling
Grafana has transitioned from legacy Sass-based styling to Emotion, a CSS-in-JS library. Developers are instructed to use the useStyles2 hook to generate memoized styles that have direct access to the theme object.
Theming Data Flow
The theming system utilizes a central theme object (GrafanaTheme2) that provides design tokens. Components consume these tokens through React Hooks or Higher-Order Components (HOCs).
This flow ensures that any changes to the core theme definitions automatically propagate through the component hierarchy.
Sources: contribute/style-guides/themes.md:8-15, contribute/style-guides/themes.md:21-35
Styling Guidelines
- Emotion over Sass: All new styles must use Emotion. Sass is deprecated and only maintained for legacy support. Sources: contribute/style-guides/frontend.md:129-131
- Class Naming: Emotion class names use camelCase (e.g.,
elementWrapper), while React component classes use PascalCase. Sources: contribute/style-guides/frontend.md:33-51 - Memoization: The
useStyles2(getStyles)hook is required to memoize style generation and prevent unnecessary re-renders. Sources: contribute/style-guides/frontend.md:53-55
Core Theme Variables
The GrafanaTheme2 object contains specific objects for different visual aspects. These variables ensure that components remain accessible and consistent across light and dark modes.
Color Palettes
The theme defines six "rich color objects" used for different semantic states:
| Color Object | Common Use Case |
|---|---|
primary | Main actions and branding |
secondary | Supplementary actions |
info | Informational callouts |
success | Positive confirmations/validations |
warning | Cautionary notices |
error | Errors and critical failures |
Sources: contribute/style-guides/themes.md:58-65
Design Tokens (Spacing & Shapes)
Grafana uses a scaling system for spacing and border radii to ensure mathematical consistency in layouts.
UI Component Library (@grafana/ui)
The @grafana/ui package exports a wide range of components categorized to help developers find the right tool for their task.
Component Categories
| Category | Examples |
|---|---|
| Forms | Input, Select, Switch, Checkbox, Field |
| General | Button, Icon, Tabs, Modal |
| Layout | Box, Stack, HorizontalGroup, VerticalGroup |
| Visualizations | Graph, Table, Gauge, BarChart |
Sources: contribute/style-guides/storybook.md:54-60, packages/grafana-ui/CHANGELOG.md:124-142
Accessibility (a11y)
Accessibility is a core requirement for UI components. Components like Field automatically handle the association between labels and form controls using unique IDs.
- Form Controls: Use React's
useIdto provide stable, unique identifiers. Sources: contribute/style-guides/accessibility.md:10-15 - Semantic HTML: Developers must use semantic elements and proper ARIA roles. Sources: contribute/create-pull-request.md:58-65
Design System Management with Storybook
Grafana uses Storybook to document and debug UI components. It allows developers to view components in isolation with various configurations.
Story Structure
Stories are co-located with their components using the *.story.tsx extension. They use the Component Story Format (CSF).
- CSF Format: Uses a default export for metadata (title, decorators) and named exports for individual stories. Sources: contribute/style-guides/storybook.md:20-40
- Controls: Replaces the deprecated "Knobs" system, allowing dynamic interaction with component props. Sources: contribute/style-guides/storybook.md:123-130
MDX Documentation
Comprehensive documentation is written in .mdx files, which combine Markdown and JSX.
Legacy Variable Management
While Emotion is preferred, some parts of Grafana still rely on Sass variables. These are automatically generated from the TypeScript theme definitions.
Generated Styles
Files ending in .generated.scss should never be edited manually. They are derived from .tmpl.ts templates.
- Entry Points:
_variables.dark.generated.scssand_variables.light.generated.scss. - Generation: Run
yarn devto regenerate these files after modifying the TypeScript sources.
Sources: contribute/style-guides/themes.md:144-158, public/sass/_variables.generated.scss:1-10
Conclusion
The UI and Theming system in Grafana represents a shift toward a highly structured, token-based architecture. By centralizing components in @grafana/ui and using Emotion for styling, the project maintains a consistent look and feel while enabling strict accessibility standards and efficient documentation via Storybook. This modular approach ensures that both core developers and plugin authors can build accessible, theme-compliant interfaces.