Deploy preview

• docs/data/common-concepts/custom-components/custom-components.md

  
  

Bundle size

Details of bundle changes

Performance

Total duration: 1,514.59 ms +56.03 ms^(+3.8%) | Renders: 63 ⁽⁺⁰⁾ | Paint: 2,118.04 ms +116.75 ms^(+5.8%)

…and 2 more (+19 within noise) — details

Metric alarms

Check out the code infra dashboard for more information about this PR.

Follow-up: tightened DataAttributes to only add the data-* index signature (commit ad974f0).

Why

DataAttributes previously intersected React.AriaAttributes as well. Every real slot inner type in this repo already inherits AriaAttributes through its element or component base:

• HTML element strings ('li', 'div', 'input', ...) resolve to React.HTMLAttributes ‚Üí AriaAttributes.
• SVG element strings ('rect', ...) resolve to React.SVGAttributes ‚Üí AriaAttributes.
• Component references resolve via React.ComponentPropsWithRef<typeof X> to whatever X declares, which in MUI X consistently descends from the HTMLAttributes/SVGAttributes hierarchy (ButtonBaseProps, PopperProps, ChartsTooltipContainerProps extends Partial<PopperProps>, etc.).
• HeatmapCellProps extends React.ComponentPropsWithRef<'rect'>, PickerDayProps extends Omit<ButtonBaseProps, ...>, GridSlotProps root/main use React.HTMLAttributes<HTMLDivElement>, and so on.

A repo-wide grep for narrow inline types (SlotComponentPropsFromProps<{ with an object-literal first argument) returned a single match: the synthetic spec added in this PR. No production slot relied on DataAttributes for aria coverage.

So including aria-* in DataAttributes was redundant for every real consumer. The cost of leaving it in was small but real:

• Aria keys showed up twice in hover popups on every widened slot union (once from the inner HTMLAttributes branch, once from the intersection with DataAttributes).
• Every conditional-type distribution over WithDataAttributes<T> had to carry the full AriaAttributes surface through with it.
• The name DataAttributes was doing two things; now it does exactly what it says.

What changed

• DataAttributes is now just DataAttributesOverrides & { [k: \data-${string}`]: DataAttributeValue }`.
• AssertAllSlotsAcceptDataAttributes drops the 'aria-label' extends keyof V probe and checks only 'data-x' extends keyof V. Failure message updated to match.
• ChartBaseCommonProps is the one type that intersects React.DOMAttributes (event handlers only) rather than React.HTMLAttributes, so it re-adds React.AriaAttributes explicitly to preserve its previous aria surface.
• Per-package slotDataAttributes.spec.ts comments updated for wording consistency.

Verification

• pnpm --filter "@mui/x-internals" run typescript - passes.
• pnpm --filter "@mui/x-charts*" run typescript - passes (including the ChartBaseCommonProps compensating change).
• pnpm --filter "@mui/x-date-pickers*" run typescript, @mui/x-tree-view*, @mui/x-data-grid*, @mui/x-chat* - all pass.
• pnpm exec prettier --check and pnpm eslint on the changed files - clean.
• All existing per-package slotDataAttributes.spec.ts assertions still pass: every slot still accepts data-*, and aria still flows through via each slot's own base type.

The runtime test in describeSlotsConformance that asserts aria-* forwarding remains unchanged and green: the underlying DOM still accepts aria regardless, and at the type level each slot's inner type already carries AriaAttributes.

Performance note

The existing perf numbers in the PR body represent the upper bound. Dropping React.AriaAttributes from the intersection strictly reduces distribution work, so the already-tiny +0.3-0.7% on type/instantiation counts only gets smaller after this follow-up.

@siriwatknp I have noticed that the majority of the slots extend some React HTML element attributes, which downstream extend the AriaAttributes. Hence, I removed the explicit aria-* attributes as that would just be extra redundant noise.

This pull request has conflicts, please resolve those before we can evaluate the pull request.

Claude Opus 4.8 reply

I verified all four against the code (tracing the runtime paths, not just the types); all four are real. Addressed in three commits: 8af03a1 (exclude non-forwarding slots), c6254be (messageActions), 445b54b (docs).

1. Fallback augmentation (P1) -- fixed. Confirmed: MUI X peer-deps @mui/material ^7.3.0 || ^9.0.0, so a Material UI 7 app (with its own @mui/utils@7) is a supported setup with two @mui/utils copies, and the consumer's declare module '@mui/utils/types' augments the wrong one. The docs now require adding @mui/utils (>= 9.2) as a direct dependency so both resolve to one copy (445b54b). I did not add an X-specific augmentation surface: that reintroduces the competing MUI-X-only augmentation API this PR deliberately removed (and that this review praises removing), so I'd rather keep the single shared surface and fix the resolution requirement in docs.

2. xAxis / yAxis (P1) -- fixed. Confirmed ChartsAxis passes the whole slotProps bag down but never applies slotProps.xAxis / slotProps.yAxis, so both data-* and the pre-existing *PropsOverrides are discarded (that runtime gap predates this PR; the widening just made it visible). Un-widened both (8af03a1). I checked the sibling container slots too -- toolbar, legend, tooltip root, and the plot leaves (mark / scatter / pieArc) all spread onto their DOM/SVG, so this is scoped to xAxis / yAxis.

3. desktopTrapFocus (P2) -- fixed, and it's worse than a silent no-op: FocusTrap renders no DOM element and its exactProp guard throws a dev-time error on unknown props, so data-* can never reach the DOM. Un-widened (8af03a1). Left desktopTransition / mobileTransition widened -- those forward through the transition clone to the Paper.

4. messageActions callback (P2) -- fixed. It was the only slot wrapping the whole object-or-callback union; rewrote it to widen each branch (matching SlotComponentPropsFromProps) so the callback return is checked like the object form (c6254be). Added a spec asserting the callback return accepts data-* on its own -- you're right that the package assertion passes as long as any union branch has the marker, so it could not have caught this.

For the excluded slots, the per-package specs now pass an explicit exclusion list rather than silently dropping them, so the exclusion is documented and a future regression on the remaining slots still surfaces.

On the aria sub-claim: correct that MuiTrapFocusProps does not inherit AriaAttributes, though it is moot for the widening itself -- DataAttributesOverrides carries only data-* keys (aria was dropped earlier), so the augmentation never adds aria. I softened the description's "every slot" wording regardless.

On the broader recommendation (make runtime forwarding a prerequisite, audit + runtime-test every slot): I'd keep that as the agreed follow-up rather than a merge gate. Tracing the widened slots, nearly all forward at runtime, and the specific non-forwarding ones you found are now excluded on the same principle as Data Grid. A full per-slot runtime-forwarding audit with runtime tests across Charts / Pickers / Chat (alongside the Data Grid work) is the tracked follow-up.

GPT 5.6 Sol Follow-up finding

[P1] slotProps.scatter still advertises data-*, but every default renderer drops it.

[ScatterPlotSlotProps.scatter](https://github.com/mui/mui-x/blob/445b54b89c77a2dd93f00cb6b1542b7989dd9fde/packages/x-charts/src/ScatterChart/ScatterPlot.tsx#L30-L32) remains wrapped in WithDataAttributes, and the props are passed to ScatterItems [here](https://github.com/mui/mui-x/blob/445b54b89c77a2dd93f00cb6b1542b7989dd9fde/packages/x-charts/src/[Scatter](https://github.com/mui/mui-x/blob/445b54b89c77a2dd93f00cb6b1542b7989dd9fde/packages/x-charts/src/ScatterChart/Scatter.tsx#L82-L124)Chart/ScatterPlot.tsx#L139-L152). However:

• svg-single: Scatter destructures known props without ...other; its <g> never receives the attributes.
• svg-batch: [BatchScatter](https://github.com/mui/mui-x/blob/445b54b89c77a2dd93f00cb6b1542b7989dd9fde/packages/x-charts/src/ScatterChart/BatchScatter.tsx#L155-L224) also discards unknown props before rendering Group.
• Progressive rendering: [ScatterAsync](https://github.com/mui/mui-x/blob/445b54b89c77a2dd93f00cb6b1542b7989dd9fde/packages/x-charts/src/ScatterChart/async/ScatterAsync.tsx#L34-L72) is a controller returning a fragment and does not pass unknown props to its batches.

Consequently this type-checks but produces no locator:

<ScatterChart
  slotProps={{
    scatter: { 'data-testid': 'scatter-series' },
  }}
/>

This directly contradicts the response’s statement that the checked plot leaves, including scatter, spread onto their SVG elements. It is the same type/runtime mismatch as the corrected xAxis/yAxis issue.

Recommended resolution: either remove WithDataAttributes from scatter and explicitly exclude it from the compile-time assertions, or define forwarding semantics for every renderer and add runtime coverage for svg-single, svg-batch, and progressive rendering.

Previous findings

The four original findings are otherwise addressed correctly:

• xAxis and yAxis are no longer widened.
• desktopTrapFocus is no longer widened.
• Both messageActions forms are widened independently, and the callback return has targeted type coverage.
• The docs now explain that fallback augmentation requires the consumer and MUI X to resolve the same @mui/utils.

Design assessment

The central design rule should be: WithDataAttributes is appropriate only when the default slot has a defined DOM root and forwards arbitrary props to it. The current compile-time test verifies only assignability; it cannot establish that an attribute reaches the DOM. The remaining scatter bug shows that postponing the runtime audit leaves the advertised contract unreliable.

Two non-blocking concerns remain:

• The test utility still says every real slot inner type inherits React.AriaAttributes, despite MuiTrapFocusProps disproving that statement.
• “Add @mui/utils v9.2.0 or later so the copies dedupe” is too absolute. A direct dependency does not itself guarantee one resolved version, especially with an existing lockfile or a future incompatible major. The docs should recommend a compatible range such as ^9.2.0 and explicitly tell consumers to verify/dedupe the lockfile.

I reviewed exact head 445b54b89c77a2dd93f00cb6b1542b7989dd9fde. Charts, Chat, and Date Pickers TypeScript checks pass, and the PR’s reported CI is green; those checks do not exercise this runtime contract. I did not post or modify anything.

All points from both reviews are addressed. Summary with commits:

Original findings

1. Fallback augmentation (P1) -- fixed, and now verified rather than argued. I built a real repro (Material UI 7.3.11 pulling @mui/[email protected], a package consuming @mui/[email protected], and tsc): without a direct @mui/[email protected] dependency the augmentation lands on Material's v7 copy and data-* is rejected; adding @mui/utils@^9.2.0 as a direct dependency makes it resolve to MUI X's v9.2 copy and it type-checks (confirmed under pnpm and npm). You were right that the v7 and v9.2 copies never dedupe -- the direct dep dedupes the two v9.2 copies, not the v7 one. Docs now say exactly this, with "upgrade Material UI to 9.2+" as the simplest fix (dc1d3bc). I did not add an X-specific augmentation surface: it reintroduces the competing MUI-X-only augmentation API this PR deliberately removed (and that the review praises removing).

2. xAxis / yAxis (P1) -- fixed. ChartsAxis passes the whole slotProps bag down but never applies slotProps.xAxis / yAxis, so both data-* and the pre-existing *PropsOverrides are dropped (that runtime gap predates this PR). Un-widened both (8af03a1).

3. desktopTrapFocus (P2) -- fixed, and worse than a no-op: FocusTrap renders no DOM element and its exactProp guard throws in dev on unknown props. Un-widened (8af03a1). desktopTransition / mobileTransition stay widened -- they forward through the transition clone to the Paper.

4. messageActions callback (P2) -- fixed. Rewrote it to widen each branch (matching SlotComponentPropsFromProps) so the callback return is checked like the object form, and added a spec asserting the callback return accepts data-* on its own (c6254be).

Follow-up finding

5. scatter (P1) -- fixed, and you were right that my "the plot leaves forward" claim was wrong. All three default renderers (svg-single Scatter, svg-batch BatchScatter, progressive ScatterAsync) destructure named props with no ...other, so data-* never reaches an element. Un-widened + excluded from the assertions (1953c3c). To avoid another round, I then traced every widened charts slot to its final element: scatter was the only remaining miss. The rest genuinely reach an intrinsic element via ...other -- marker -> <circle>, mark -> styled path/circle, pieArc/pieArcLabel, funnelSection/funnelSectionLabel, cell -> <rect>, tooltip/root -> Popper div, and the four axis leaves.

Non-blocking

6. The assertion helper's aria comment no longer claims every slot inner type inherits React.AriaAttributes (MuiTrapFocusProps disproves it); it now states aria isn't checked because the widener only adds data-* keys (DataAttributesOverrides has no aria keys) (67f8807).

7. The "add @mui/utils and it dedupes" guidance was too absolute -- rewritten per the verified repro in point 1 (two copies coexist; the direct dep only collapses the v9.2 copies).

On the design rule (widen only where the default slot has a DOM root that forwards): agreed, and the scatter miss is a fair hit against a compile-time-only check. I've now applied that rule across the full charts surface by tracing each slot; a broad per-slot runtime-forwarding test sweep across Charts / Pickers / Chat, plus Data Grid, stays the tracked follow-up rather than a merge gate.

GPT 5.6 Sol Findings

[P1] ScatterChartPremium.tooltip is still not widened

ScatterChartPremiumSlotProps removes the community tooltip definition and reintroduces it without WithDataAttributes:

tooltip?: Partial<ChartsTooltipProps<'item' | 'none'>> & TooltipPropsOverrides;

This makes Premium inconsistent with both ScatterChart and ScatterChartPro. A strict probe against the exact head produces:

TS2353: 'data-followup' does not exist in type
'Partial<ChartsTooltipProps<"none" | "item">> & TooltipPropsOverrides'

Yet the runtime does forward these props into ChartsTooltip here, so this is precisely a slot that should be widened.

The reason CI misses it is that the Premium assertion suite does not include ScatterChartPremiumSlotProps; despite claiming package-wide coverage, it currently covers only Bar, Candlestick, container/provider, and Heatmap types.

Recommended fix:

• Prefer inheriting the already-correct community tooltip definition instead of omitting and recreating it; or wrap the recreated type in WithDataAttributes.
• Add assertions for ScatterChartPremiumSlotProps, with xAxis | yAxis | scatter explicitly excluded.
• Audit the other exported Premium types currently absent from the suite, especially Radial Bar and Radial Line.

[P2] The documented augmentation fails in a standalone declaration file

The example begins directly with declare module '@mui/material/utils'.

If a consumer follows “augment … once, anywhere in your project” by placing that block in a standalone mui.d.ts without imports or exports, TypeScript treats it as an ambient module declaration rather than augmentation. I reproduced this against Material/UI Utils 9.2: data-* remained rejected. Adding this line made the same repro pass:

import type {} from '@mui/material/utils';

That import should be included in the snippet. The @mui/utils/types fallback needs the equivalent import when shown as a standalone declaration.

[P2] The Material v7 fallback incorrectly calls its Utils copy “unused”

The warning says Material v7’s @mui/utils@7 copy “stays separate and unused.” It is still used internally by Material v7; only the consumer’s augmentation is redirected to the v9.2 copy used by MUI X.

More importantly, this workaround only enables data-* on MUI X slots. It does not retrofit Material v7 slots with the v9.2 augmentation mechanism. The docs should state that explicitly:

Material UI continues using its v7 copy. The direct v9.2 dependency makes the augmentation reach MUI X slots only.

The preceding claim that Material 9.2+ “always” resolves one shared copy is also stronger than package managers guarantee when an existing lockfile or override preserves different compatible 9.x versions. “Normally resolves” plus the same lockfile verification advice would be more accurate.

Claude Opus 4.8 reply

All three addressed (224af3e, 2bb1459, 6be5f68):

[P1] ScatterChartPremium.tooltip -- fixed. It re-declared the slot without WithDataAttributes while the tooltip forwards to the DOM at runtime, so it's now widened like community/pro. The gap hid because the premium spec covered only 5 of 14 exported *SlotProps; I added the rest (ScatterChartPremium, RadialBarChart, RadialLineChart, the geo/radial providers, and the bar/scatter/radial plot types), excluding xAxis/yAxis/scatter where present. I also grepped every charts package for the same re-declare-without-widening pattern -- tooltip was the only instance -- and confirmed no other top-level component is missing from a suite (SankeyChart etc. are covered).

[P2] standalone declaration file -- fixed, and confirmed with a repro: augmenting the re-export @mui/material/utils in a standalone .d.ts without a module marker is treated as an ambient declaration and data-* stays rejected; adding import type {} from '@mui/material/utils' makes it real augmentation. Added that import to the snippet and noted the same for the @mui/utils/types fallback.

[P2] wording -- fixed. Material UI v7 keeps using its own @mui/utils copy; the direct v9.2 dependency only redirects your augmentation, so it enables data-* on MUI X slots, not Material UI v7 slots. Softened "always resolves one shared copy" to "normally", with the lockfile/override verification caveat.

On coverage scope: the specs assert every top-level component and provider *SlotProps (the surfaces you pass slotProps to); nested slot props (plot elements, use* hooks) are exercised through their parent. I corrected the comments to say that instead of "every exported type".

Final GPT 5.6 Sol follow-up review

No further findings.

I verified the two follow-up commits on the exact PR head, 619379a09e09943fd29367103d3bd30636d14bfe.

Verified fixes

1. Material UI 7 documentation

   The documentation now correctly requires both parts of the workaround:

   • augment @mui/utils/types, rather than @mui/material/utils;
   • install @mui/utils@^9.2.0 as a direct dependency so the consumer augmentation and MUI X resolve to the same v9.2 copy.

   It also correctly explains that this enables data-* only on MUI X slots, not Material UI 7 slots.

2. Central callback regression guard

   The new x-internals spec independently extracts the callback branch of SlotComponentPropsFromProps and validates its return type. This closes the existential-union blind spot in the package-wide assertions: widening only the object branch can no longer keep the suite green.

   The test is included by the x-internals src/**/* TypeScript configuration, and the exact-head x-internals typecheck passes.

Final assessment

• The previously reported implementation and documentation issues are addressed.
• The new changes are narrowly scoped and consistent with the design.
• git diff --check is clean.
• Current CI already has the type, lint, package, static, regression, browser, and one e2e checks passing. Some remaining lanes and the deploy preview were still pending when checked.

Verdict: looks good to merge once the remaining CI checks finish successfully.