AG-Grid-React-Series-#47-Custom-Themes-in-AG-Grid-React

Welcome back to our AG-Grid React series! In this installment, we're diving deep into one of the most powerful features for tailoring your grid to perfection: custom themes. While AG-Grid provides a range of beautiful, ready-to-use themes, the ability to create your own allows you to seamlessly integrate the grid into your application's unique branding and design language.

Whether you need to match corporate colors, enhance accessibility, or simply achieve a specific aesthetic, customizing AG-Grid's appearance is crucial. Let's explore how to take full control of your grid's look and feel.

Understanding AG-Grid's Theming Architecture

Before we jump into customization, it's helpful to understand how AG-Grid handles themes. The grid's styling is primarily managed through CSS. AG-Grid offers a modular CSS structure, making it highly customizable.

• Core Styles: These are the fundamental styles that define the grid's layout and functionality, independent of any theme.
• Theme Styles: These build on the core styles, applying specific colors, fonts, borders, and spacing to create a distinct visual theme (e.g., Alpine, Balham, Quartz).

When you apply a built-in theme, you're essentially importing a CSS file that applies a set of styles, often defined using CSS variables, to your grid. For instance, applying the Alpine theme typically involves importing:

import 'ag-grid-community/styles/ag-grid.css'; // Core grid CSS
import 'ag-grid-community/styles/ag-theme-alpine.css'; // Alpine theme CSS

// ... inside your component
<div className="ag-theme-alpine" style={{ height: 400, width: 600 }}>
    <AgGridReact rowData={rowData} columnDefs={columnDefs} />
</div>
    

Why Custom Themes?

While built-in themes are great for quick setup, custom themes offer significant advantages:

• Brand Consistency: Ensure the grid matches your application's color palette, typography, and overall design language.
• Unique User Experience: Differentiate your application with a bespoke look and feel.
• Accessibility: Implement specific color contrasts, font sizes, or focus indicators to meet accessibility standards.
• Design System Integration: Align AG-Grid with an existing design system by adopting its tokens and components.

Methods for Customizing AG-Grid Themes

AG-Grid provides several powerful ways to customize its appearance, ranging from simple CSS variable overrides to full SASS-based theme creation.

Method 1: Overriding CSS Variables (Recommended for Quick Customization)

The easiest and most common way to customize an AG-Grid theme is by overriding its CSS variables. AG-Grid's built-in themes are heavily reliant on CSS custom properties (variables), which makes them incredibly flexible.

You can inspect any AG-Grid element in your browser's developer tools to find the relevant CSS variables (prefixed with `--ag-`). These variables control almost every aspect of the grid's appearance, from colors and borders to spacing and font sizes.

How to Implement:

1. Import a Base Theme: Start by importing one of AG-Grid's existing themes, as it provides the structural CSS.
2. Define Overrides: In your global CSS file (e.g., index.css) or a component-specific CSS module, target the theme class and override the desired CSS variables.

Example: Customizing the Alpine Theme

Let's say we want to change the primary accent color, header background, and border color of the ag-theme-alpine theme.

First, your React component might look like this:

import React, { useMemo } from 'react';
import { AgGridReact } from 'ag-grid-react';

import 'ag-grid-community/styles/ag-grid.css';
import 'ag-grid-community/styles/ag-theme-alpine.css'; // Import the base theme

// Import your custom styles AFTER the base theme
import './MyGridTheme.css';

const MyCustomGrid = () => {
    const rowData = useMemo(() => [
        { make: "Toyota", model: "Celica", price: 35000 },
        { make: "Ford", model: "Mondeo", price: 32000 },
        { make: "Porsche", model: "Boxster", price: 72000 }
    ], []);

    const columnDefs = useMemo(() => [
        { field: "make" },
        { field: "model" },
        { field: "price" }
    ], []);

    return (
        <div className="ag-theme-alpine my-custom-theme" style={{ height: 400, width: 600 }}>
            <AgGridReact rowData={rowData} columnDefs={columnDefs} />
        </div>
    );
};

export default MyCustomGrid;
    

Now, create MyGridTheme.css:

/* MyGridTheme.css */

/* Target the combined theme class for specificity */
.ag-theme-alpine.my-custom-theme {
    /* Primary brand color */
    --ag-foreground-color: #3f51b5; /* Default text color */
    --ag-accent-color: #3f51b5; /* Primary accent color for selections, etc. */
    --ag-secondary-border-color: #c5cae9; /* For borders inside the grid */

    /* Header styling */
    --ag-header-background-color: #f5f5f5;
    --ag-header-foreground-color: #333;
    --ag-header-column-separator-color: #e0e0e0;
    --ag-header-border-color: #e0e0e0;

    /* Row styling */
    --ag-row-hover-background-color: #e8eaf6; /* Light hover effect */
    --ag-row-alt-background-color: #f8f9fa; /* Zebra striping */

    /* Grid borders */
    --ag-border-color: #ccc;
    --ag-cell-horizontal-border: solid #eee 1px; /* Horizontal borders between cells */

    /* Font adjustments */
    --ag-font-size: 14px;
    --ag-font-family: 'Roboto', sans-serif;
}

/* You can also target specific elements more directly if needed,
   but prioritize CSS variables for maintainability. */
.ag-theme-alpine.my-custom-theme .ag-header-cell-label {
    font-weight: bold;
}
    

In this example, we apply both ag-theme-alpine (for the base styles) and our custom my-custom-theme class. The CSS in MyGridTheme.css then targets .ag-theme-alpine.my-custom-theme to ensure our overrides have sufficient specificity.

Important: Always import your custom CSS file after the base AG-Grid theme CSS to ensure your overrides take precedence.

Method 2: Using SASS/SCSS Variables (For Deeper Customization and New Themes)

For more extensive customization, or if you're building a theme from scratch, AG-Grid's SASS variables provide the ultimate control. AG-Grid's themes are built using SASS, and you can leverage their SASS files to define your own variables and generate a completely custom theme.

This method is ideal when you need to change more than just colors and spacing, or if your project already uses SASS for styling.

How to Implement:

1. Install SASS: Ensure your project is set up to compile SASS/SCSS. (e.g., using node-sass or sass package).
2. Create a Custom SCSS File: Create a new SCSS file (e.g., src/scss/my-custom-ag-theme.scss).
3. Import AG-Grid SASS: Import AG-Grid's core SASS files and the theme you wish to base yours on.
4. Override SASS Variables: Before importing the theme, override the AG-Grid SASS variables. These variables are well-documented in the AG-Grid source code (look for node_modules/@ag-grid-community/styles/scss/_ag-grid-variables.scss and _ag-theme-quartz-vars.scss for examples).
5. Apply the Theme: In your React component, use the name you gave your custom theme as the class name.

Example: Building a Custom SASS Theme (Based on Quartz)

Let's create a new theme called ag-theme-my-custom.

Create src/scss/my-custom-ag-theme.scss:

/* src/scss/my-custom-ag-theme.scss */

// 1. Import AG-Grid's core styles first
@import '~ag-grid-community/styles/ag-grid.scss';

// 2. Override AG-Grid SASS variables *before* importing a base theme
// These variables control colors, spacing, borders, etc.
// Check AG-Grid's node_modules/@ag-grid-community/styles/scss/ for a full list (e.g., _ag-theme-quartz-vars.scss)

// Primary brand colors
$ag-quartz-primary-color: #6200EE; // A deep purple
$ag-background-color: #f7f9fc; // Light background for the grid itself
$ag-border-color: #e0e0e0;

// Header styling
$ag-header-background-color: #f0f4f8;
$ag-header-foreground-color: #333;
$ag-header-column-resize-handle-color: $ag-quartz-primary-color;

// Row styling
$ag-row-hover-color: #ede7f6; // Lighter purple on hover
$ag-odd-row-background-color: #ffffff; // Keep odd rows white
$ag-even-row-background-color: #fefefe; // Slightly off-white for even rows

// Font settings
$ag-font-family: 'Open Sans', sans-serif;
$ag-font-size: 13px;

// 3. Import a base theme (e.g., Quartz) or core theme utilities
// This will apply the overridden variables
@import '~ag-grid-community/styles/ag-theme-quartz.scss';

// 4. Optionally, add more custom CSS rules directly
.ag-theme-my-custom {
    .ag-header-cell-label {
        font-weight: 600;
        text-transform: uppercase;
    }
    .ag-cell {
        padding-top: 8px;
        padding-bottom: 8px;
    }
}
    

Now, in your React component, import this SCSS file and apply the class name:

import React, { useMemo } from 'react';
import { AgGridReact } from 'ag-grid-react';

import 'ag-grid-community/styles/ag-grid.css'; // Core grid CSS (still needed for layout)
import './scss/my-custom-ag-theme.scss'; // Import your custom SCSS theme

const MySassThemedGrid = () => {
    const rowData = useMemo(() => [
        { make: "Tesla", model: "Model 3", price: 50000 },
        { make: "BMW", model: "X5", price: 60000 },
        { make: "Mercedes", model: "C-Class", price: 45000 }
    ], []);

    const columnDefs = useMemo(() => [
        { field: "make" },
        { field: "model" },
        { field: "price" }
    ], []);

    return (
        <div className="ag-theme-my-custom" style={{ height: 400, width: 600 }}>
            <AgGridReact rowData={rowData} columnDefs={columnDefs} />
        </div>
    );
};

export default MySassThemedGrid;
    

When your SASS compiler runs, my-custom-ag-theme.scss will generate a CSS file containing all the AG-Grid styles with your overridden variables.

Method 3: Direct CSS Overrides (Use Sparingly)

Occasionally, you might need to apply a very specific style that isn't easily controlled by CSS or SASS variables. In these cases, you can directly override AG-Grid's internal class names using plain CSS.

While this offers maximum flexibility, it's generally less recommended because it can be fragile. AG-Grid's internal class names might change in future updates, potentially breaking your styles. Prioritize CSS/SASS variables whenever possible.

Example: Increasing font size for all cells

/* In your component's CSS or a global stylesheet */
.ag-theme-alpine.my-custom-theme .ag-cell {
    font-size: 16px; /* Directly target the cell class */
    line-height: 20px;
    padding-top: 10px; /* Adjust padding if needed */
    padding-bottom: 10px;
}
    

Always ensure your direct overrides are scoped correctly (e.g., by combining with your custom theme class) to avoid unintended global styling changes.

Best Practices for Custom Theming

• Start with a Base Theme: Even if you want a heavily customized look, it's often easier to start by importing one of AG-Grid's built-in themes (e.g., Alpine, Quartz) and overriding its variables. This provides a solid foundation and reduces the amount of CSS you need to write.
• Prioritize CSS Variables: Whenever possible, use CSS custom properties (variables) for customization. They are robust, easy to understand, and less likely to break with AG-Grid updates compared to direct class name overrides.
• Keep Overrides Organized: Group your custom CSS/SASS in a dedicated file (e.g., MyGridTheme.css or my-custom-ag-theme.scss) to keep your project clean.
• Use Specificity Wisely: When overriding, ensure your CSS rules are specific enough to target only the desired elements within your themed grid, but not overly specific to become brittle. Using a wrapper class (like .my-custom-theme) is an excellent way to scope your styles.
• Test Across Browsers: Always test your custom themes in different browsers to ensure consistent rendering.
• Refer to AG-Grid Documentation & Source: The official AG-Grid documentation on theming is comprehensive, and inspecting the AG-Grid SASS source files (in node_modules/@ag-grid-community/styles/scss/) can reveal all available variables and mixins.

Conclusion

Custom themes are an incredibly powerful feature of AG-Grid, allowing you to seamlessly integrate this robust data grid into any application's design system. By leveraging CSS variables or the more advanced SASS theming, you gain granular control over every visual aspect, ensuring your grid not only functions brilliantly but also looks exactly as you envision.

Experiment with these methods to craft a unique and branded experience for your users. Happy theming!