[data grid] Theming – Questions, Issues, and Inconsistencies

Hello MUI Team,

At sipgate, we are developing a central design system and recently started using MUI X DataGrid Premium (v8.8).

Our goal is to create a consistent base theming (colors, icons, fonts, etc.) based on our Design Foundation, so that other teams can use the DataGrid without additional styling effort.

Our color system is based on alias tokens (semantic), following the W3C “Alias Tokens” draft, which is now a widely adopted industry standard within the design community. We understand that MUI is built on Material 3. However, in the case of DataGrid, we are missing a clear theming concept and sufficient documentation that explains which theming attribute affects which specific part of the component.

Especially in the case of DataGrid, this results in:

• A confusing and unpredictable system
• No clearly discernible structure for how semantic tokens are expected to influence appearance
• Difficulty in maintaining a scalable and maintainable design approach
• Unnecessarily complex theming due to lack of transparency

Currently, inconsistent naming and unclear mapping (e.g., colors, icons, etc.) make it difficult to implement and maintain a clean theme.

We would prefer not to rely solely on overwriting styles, as this makes maintenance harder in the long run.

For the next step, we have listed a few examples of inconsistencies or ambiguities in the theming — there are definitely more to be found. We are also open to tips, suggestions, or guidance, as it is entirely possible that we have not found the right documentation or may not fully understand the intended concept.

1. Theming – Colors

Main issues:

• No clear documentation showing how color tokens are linked to DataGrid UI elements
• Token names are often non-semantic, unpredictable, or inconsistent
• Some palette values are not used in the DataGrid where they would match

1.1 Palette → Grey

• Grey palette values are not really used in the DataGrid.
• Example: grey700 affects ColumnMenu tooltips, but cells use the browser default tooltip styling.
• Borders, text, and icons are not linked to Grey tokens at all.

👉 Code Example 1.1

1.2 Palette → Actions (Naming & Behavior)

• Many icons use actions -> active as their default color fill.
• selected changes some component background like chip background rather than indicating a selected icons, cells or something like this.
• Hover colors differ:
  • MenuListItems → predictable hover colors
  • DataGrid rows → less predictable hover colors because its a calculated color out of the hover value (thats how material works).

👉 Code Example 1.2

Wish (Request):
A consistent, well-documented theming structure with a transparent token hierarchy — whether based on Material 3 color tokens or the W3C alias token approach.

2. Theming – Icons

👉 (All in one) Code Example

2.1 Missing centralized replacement points

• Some icons (e.g., Pagination) can only be replaced directly on the component, not via DataGrid slots.
• This is inconsistent and inconvenient.

2.2 Inconsistent slot naming

FilterPanel

• filterPanelRemoveAllIcon
• filterPanelDeleteIcon

Mixing “Remove” and “Delete” is confusing.
💡 Suggestion: consistent naming + a single point of configuration.

Column Selector / Menu

• columnSelectorIcon
• columnMenuManageColumnsIcon

Both open the same menu but must be replaced separately.

Positive example:

• quickFilterIcon — set once, used in multiple places (Toolbar search and ColumnMenu search).

2.3 Inconsistent icon logic in similar features

• Pinned Left/Right: One icon that disappears when unpinned.
• Grouping: Changes between “Group” and “Ungroup” icons.

💡 Suggestion: unify icon logic so similar actions use similar patterns.

3. Theming – Fonts

Issue:

• line-height behaves differently in ColumnHeader vs. Cell:
  • ColumnHeader: text remains centered (controlled by parent element).
  • Cell: line-height directly affects vertical alignment.
• Leads to:
  • Misalignment
  • Poor text selection appearance (highlight fills entire cell)

👉 Code Example

Wish (Request):

• Make vertical alignment stable regardless of line-height
• Ensure consistent appearance across headers and cells

4. Theming – Spacings

The spacing theming has no clear or direct impact. Adjusting it primarily leads to inconsistent spacing in MenuItems within MenuList or in other features, which makes the layout appear broken.

Summary of Requests

• 📖 Clear, centralized theming documentation explaining the impact of each token and attribute
• 🏷 Consistent naming of theming properties and slots
• 🎯 Centralized icon slots without heavy overwriting

We hope our examples make the issues clear and are happy to provide more test cases or demos.
Looking forward to your feedback — and open to guidance if we have misunderstood existing concepts.

Your environment

System:
    OS: macOS 15.6
  Binaries:
    Node: 22.17.0 - ~/.nvm/versions/node/v22.17.0/bin/node
    npm: 10.9.2 - ~/.nvm/versions/node/v22.17.0/bin/npm
    pnpm: Not Found
  Browsers:
    Chrome: 138.0.7204.184
    Edge: 139.0.3405.86
    Safari: 18.6
  npmPackages:
    @emotion/react:  11.14.0 
    @emotion/styled:  11.14.1 
    @mui/core-downloads-tracker:  7.2.0 
    @mui/material:  7.2.0 
    @mui/private-theming:  7.2.0 
    @mui/styled-engine:  7.2.0 
    @mui/system:  7.2.0 
    @mui/types:  7.4.4 
    @mui/utils:  7.2.0 
    @mui/x-charts:  8.8.0 
    @mui/x-charts-pro:  8.8.0 
    @mui/x-charts-vendor:  8.5.3 
    @mui/x-data-grid:  8.8.0 
    @mui/x-data-grid-premium:  8.8.0 
    @mui/x-data-grid-pro:  8.8.0 
    @mui/x-internal-gestures:  0.2.1 
    @mui/x-internals:  8.8.0 
    @mui/x-license: 8.8.0 
    @mui/x-telemetry:  8.5.3 
    @types/react:  18.0.25 
    react: ^18.2.0 => 18.2.0 
    react-dom: ^18.2.0 => 18.2.0 
    typescript: 5.7.3 => 5.7.3 

Search keywords: theme, datagrid, colors, tokens, icons, consistency, naming convention

Order ID: 116257

Search keywords: