[RFC] enhance*Density — opt-in component density presets

[siriwatknp]

What's the problem?

Material UI components ship the comfortable Material Design spacing. Teams building data-dense, professional UIs (dashboards, admin consoles, design tools) routinely need denser layouts — and some need roomier ones.

There's an existing Density page, but it's a per-component workaround, not a density system:

• No single mechanism. It's a grab-bag of defaultProps — size: 'small' on Button, dense: true on ListItem, variant: 'dense' on Toolbar, margin: 'dense' on inputs — a different prop per component.
• Only 13 components. Button, Fab, FilledInput, FormControl, FormHelperText, IconButton, InputBase, InputLabel, ListItem, OutlinedInput, Table, TextField, Toolbar — nothing else.
• One step, one direction. A single "denser" toggle; no tunable scale, no roomier direction.
• Not holistic — by its own warning. The page states "you should not apply this theme to your whole application," so it can't be the app-wide density dial teams actually want.

Beyond that page, the only levers are styleOverrides and sx calc — re-deriving every component's internal pixel math by hand, per size (Button padding, OutlinedInput block/inline padding, Checkbox hit area, the Switch's interlocked thumb geometry). There is no single, predictable knob.

Material 3 itself documents spacing as a deliberate, adjustable system — compact vs. comfortable off one consistent scale (Applying spacing). A Material UI app can't express that today without forking component source.

This RFC proposes three built-in, opt-in presets — enhanceHighDensity / enhanceMediumDensity / enhanceLowDensity. You pick a preset, the whole component set reflows off its scale. An unconfigured app renders today's exact pixels (zero Argos diff) and ships no extra CSS variables.

What are the requirements?

1. Opt-in preset dials. Three preset functions retune density across the component set — no per-component editing, no calc for the consumer. You pick a preset, not tune a scale (mirrors enhanceHighContrast / enhanceColorScheme).
2. Holistic, off one scale. The whole UI reflows off one shared, per-component-aware scale per preset — not a naive global spacing multiplier (which has no per-component nuance and breaks coupled geometry like the outlined input's floating label).
3. Non-breaking, zero cost when unused. An unconfigured theme is pixel-identical to today (Argos zero-diff) for every (variant, size) cell, and emits no extra vars.
4. Predictable coverage. A repeatable internal authoring pattern, so rolling density across components is systematic, not ad hoc.
5. Spacing + coherent size. Three axes reflow together: spacing (padding/gap/margin/inset) off the shared scale, sizing (width/height/min-height) as raw px, and font-size/line-height + icon fontSize for any component with a size-carrying prop (size, dense, or equivalent). The discriminator is just "does it have a size-carrying prop": if so, everything that already moves with the size step moves with density — text type (Button small≠large, ToggleButton 13/15, MenuItem body1↔body2) and icon glyphs sized by fontSize (Checkbox/Radio icon 24/20, Rating star 18/24/30). Otherwise high gives tiny padding with full-size text/icons — incoherent. Type/icon is fed by each preset's typography config, not the px scale (line-height is unitless); presets may diverge on type independently (in the prototype, high reflows the full type ramp, low adjusts button type only, medium keeps default type). A component with no size-carrying prop keeps today's type/icon frozen.

What are our options?

Public shape. Three opt-in presets — enhanceHighDensity / enhanceMediumDensity / enhanceLowDensity — mirroring the existing enhanceColorScheme / high-contrast helpers. Not a first-class createTheme({ density }) node, so unconfigured apps stay lean, and not a public scale option — each preset's scale (shape/steps, per-component step mappings) is settled internally.

Internal mechanism — emitted theme overrides, zero component-source changes. Each preset computes every covered component's density-bearing values off its scale and emits them as theme styleOverrides against the selectors the component already ships — its size/dense variants, its slots. Theme styleOverrides win over built-in styles, so the targeted (variant, size) reflows; no preset → nothing emitted → today's exact pixels. Component source is completely untouched — no per-property CSS-var chain baked into styled source, no render-time branching. The per-component mapping (which value reflows off which scale step, per built-in (variant, size)) is authored directly inside each preset — no exported map layer — and kept machine-checkable by a generated emission snapshot + parity test. (Earlier drafts explored per-property var chains in component source — two- and three-layer token models — and exported private_* map constants; both were dropped once emission proved it could reproduce the exact pixels with zero source changes.)

Calc-coupled geometry — one private var, decided per component. A flat emitted value can't express a dimension that derives from another across sub-elements. For those, the preset emits one private CSS var (--_*) inside the overrides and derives the coupled values from it with calc, so connected pieces stay aligned at any density — still zero source changes. Current set: the outlined input's floating-label bridge (--_outlinedInputPadBlock → label --_restY/--_shrinkY via :has()), filled/standard input block padding (--_filledInputPadTop/Bottom, --_inputPadTop/Bottom/MarginTop), Autocomplete input padding, Tooltip arrow (--_arrowSize), Chip height (--_height), Switch thumb/track geometry (--_height/--_pad/--_thumbSize), Dialog paper margin (--_dialogMargin → the 100% - margin×2 viewport calcs; media-query guards stay static — vars can't reach @media), PaginationItem height (--_height → pill radius h/2). Which dimensions get a var is decided per component during rollout.

Token granularity. Per-component, not a fixed 4-side schema: start from the broadest shorthand and split a side out only when the implementation derives from it (e.g. OutlinedInput splits block padding because the floating label's offset derives from it). Keeps the surface lean and structure-true.

Slot emission (root vs portal). Each preset writes into components.Mui<Component>.styleOverrides, keyed by slot. Default = root (or a separately-themed sub-component's own root, e.g. MuiMenuItem, which is targeted directly so it works inside a portal). Exception: when a value is consumed by a slot that renders through a portal (Popper/Popover/Modal), it must be emitted on the portal slot, not root. Canonical case: Autocomplete — box/tag values on root, but option/listbox values on the listbox (popper) slot, since the options render outside root. A component's mapping can therefore split across slots ({ root, listbox, … }).

Base inheritance. When a derived component inherits a value from a public base it styled()-extends without overriding it (standard Input ← InputBase input padding), the preset emits on the base's theme key (MuiInputBase.styleOverrides) and the derived inherits it through the normal cascade. Components that override the inherited value (OutlinedInput/FilledInput input padding; the ButtonBase family's padding: 0 reset) get their own emission on their own key.

JS-gated dimensions — theme defaultProps (cross-package, MUI X Data Grid). Some dimensions never reach CSS at all: the Data Grid's row/header heights feed the virtualizer's JS math (row positions, scroll height) and land in the DOM as inline styles — a styleOverrides height would desync virtualization. For those, each preset attaches theme defaultProps instead: rowHeight 28/40/60 (high/medium/low) with columnHeaderHeight on the same bases, spread so an app's own theme defaults win. The grid's own density prop stays unset — its fixed ×0.7/×1/×1.3 multiplier stops cannot express a 1.5× low-density ratio (floor(base × 1.3) never lands on 60) while exact per-preset bases can, and the grid's toolbar density selector keeps working as a relative multiplier on top of the preset base. Everything else in the grid (cell/header insets, toolbar/footer/panel paddings, Pro/Premium chrome sizing) rides the same emitted styleOverrides, and grid chrome built from Material components (column menu, TablePagination, checkboxes, filter fields) reflows through the Material emissions with no grid-specific work.

Proposed solution

Three presets — the sole public density entry:

import {
  createTheme,
  enhanceHighDensity,
  enhanceMediumDensity,
  enhanceLowDensity,
} from '@mui/material/styles';

// Pixel-identical to today — no preset applied.
const theme = createTheme({ cssVariables: true });

// Denser / roomier apps — pick a preset; the whole UI reflows off its scale.
const high = enhanceHighDensity(createTheme({ cssVariables: true }));
const medium = enhanceMediumDensity(createTheme({ cssVariables: true }));
const low = enhanceLowDensity(createTheme({ cssVariables: true }));

Value	Behavior
no preset	Pixel-identical to today (zero-diff), no extra vars
enhanceHighDensity(theme)	Whole UI reflows denser off the high-density scale
enhanceMediumDensity(theme)	Whole UI on the medium scale
enhanceLowDensity(theme)	Whole UI reflows roomier off the low-density scale

Each preset ships a named --mui-density-* step scale on the theme's own CSS-variables channel (materialized at the theme's rootSelector by ThemeProvider — no CssBaseline requirement) and emits each component's overrides against it. The emitted overrides + per-component mapping are what this RFC signs off, so coverage is predictable. Scale shape/steps and per-component step-mappings are settled internally and out of this RFC's scope.

Scope. Spacing + sizing + (for components with a size-carrying prop) font-size/line-height/icon-fontSize, for each component's built-in sizes. Out of scope: the internal scale design, density as a createTheme node, typographic/icon scaling of components with no size-carrying prop, and custom (theme-added) size density (a custom size falls back to today's pixels; deferred, opt-in follow-up).

Currently covered (prototype #48749). 32 Material families verified & surfaced in the playground: Button (incl. IconButton) · ButtonGroup · Menu (MenuItem, List) · Tooltip · TextField (OutlinedInput, FilledInput, standard Input, InputBase, InputLabel, InputAdornment) · Select · Autocomplete · Tabs · Accordion · Checkbox · Radio · Switch (calc-coupled thumb/track geometry) · SvgIcon · Chip · Alert · Card · Avatar · Badge · ToggleButton · Breadcrumbs · Stepper · LinearProgress · Table (TableCell, TableSortLabel, TablePagination) · Slider · Divider · Toolbar (responsive regular/dense bar heights) · Dialog (title/content/actions + paper margin with viewport-calc coupling) · Fab · Pagination · ListItemButton · SnackbarContent · BottomNavigation. Cross-package: MUI X Data Grid — heights via theme defaultProps (row 28/40/60, header on the same bases; grid density prop unset), insets/toolbar/footer/panels/menu/quick-filter/overlays and Pro/Premium chrome (header filters, grouping indent, pivot/AI/charts panels, sidebar) via emitted styleOverrides. MUI X Tree View — item indentation via defaultProps.itemChildrenIndentation carrying a density-var string (the indentation var is set as an inline style on the tree root, so styleOverrides can't reach it; the string prop passes through verbatim — the prop value stays CSS), row height via the component's own --TreeView-itemHeight hook (unset upstream → the no-preset state stays pixel-identical), content paddings/gap via steps with the depth-indent calc re-emitted on a step base. MUI X Date/Time Pickers — day geometry via one private --_daySize var on the day-calendar root (re-points --PickerDay-size, drives weekday/week-number boxes + the 6-week container calcs whose master values are build-time JS constants), root box/buttons/clock-section widths raw per preset, header/toolbar/clock spacing via steps. All prototyped from the Material presets as untyped keys — the production home (Material-side vs an X-side enhancer consuming the same scale) is an open packaging decision. Remaining candidates (no emissions yet): Rating, the List content family (ListItem, ListItemText, ListSubheader), form wrappers (FormControl, FormHelperText, FormLabel), AvatarGroup, ToggleButtonGroup, SpeedDial, MobileStepper — plus prop-driven sizing (CircularProgress size, ImageList gap) now expressible through the defaultProps channel.

Prototype — TODOs

Prototype PR: #48749 · live playground: https://deploy-preview-48749--material-ui.netlify.app/experiments/density-playground/

• Three enhance*Density presets emitting theme styleOverrides — zero component-source changes; 32 Material families + MUI X Data Grid, Tree View, and Date/Time Pickers verified & surfaced
• Slot-aware emission — overrides on root by default, on the portal slot for portaled content (Autocomplete listbox, Tooltip tooltip)
• font-size/line-height + icon-fontSize reflow for size-carrying (size/dense) components — from the preset's typography config, not the px scale
• :has() label bridge so OutlinedInput + floating InputLabel move together, centered at any density (private --_* var emitted inside the overrides)
• Interactive playground — flip presets, inspect/override every emitted value, visual-debug overlays, export a standalone density.ts
• Local zero-diff harness (density:shot) asserting the unconfigured render is pixel-identical to master
• MUI X Data Grid coverage — heights via theme defaultProps (28/40/60; grid density prop unset), panels/pro/premium chrome via styleOverrides, playground family with grid demos
• MUI X Tree View + Date/Time Pickers coverage — indentation via a density-var string defaultProps (inline-style var seam), day geometry via a private day-size var re-pointing the component's own var, playground families with tree/calendar/clock demos
• Switch interlocked geometry derived with calc (thumb centered under density scaling)
• Installable build via pkg.pr.new + upstream Argos zero-diff across the combined set
• Docs page customization/density refresh

Decision need

1. Function shape — enhanceDensity(theme, { scale }) → decided: three presets enhanceHighDensity / enhanceMediumDensity / enhanceLowDensity (you pick a preset, not tune a scale; mirrors enhanceHighContrast / enhanceColorScheme).
2. Internal-only mapping — decided: the per-component mapping is inlined in the presets (no exported map constants, no public per-component var surface); the calc-coupling --_* vars are internal and undocumented. The presets are the sole public surface.
3. Per-side var naming (internal convention, shared with the upcoming state-color-tokens work) — decided: property-mirror camelCase, component-prefixed (--_filledInputPadTop/--_filledInputPadBottom). Block sides use Top/Bottom (never flip under RTL); an inline-axis single side, when first needed, uses the logical form (PadInlineStart/PadInlineEnd), never physical left/right.

Known constraint (not a question): the outlined-input label bridge uses :has() (Chrome 105 / Safari 15.4 / Firefox 121) — confirm the support baseline at ship time.

Resources and benchmarks

• Prototype PR (combined, installable): [WIP][prototype] density system #48749 — density playground
• Experiment PR: [material-ui] CSS-var density adapter experiment #48624
• Existing (superseded) Density page: https://mui.com/material-ui/customization/density/
• Material 3 — Applying spacing: https://m3.material.io/styles/spacing/applying-spacing
• Decision records: docs/adr/0001-css-var-density-adapter.md, docs/adr/density-adapter-rollout.md

Search keywords:

[mj12albert]

Could we consider an API surface similar to breakpoints:

// Opt-in by explicitly setting `density`
const theme = createTheme({
  cssVariables: true,
  density: {
    scale: 'compact', // 'normal' | 'comfortable' | CustomDensityScale
  },
});

const theme = createTheme({
  cssVariables: true,
  density: {
    scale: {
      xxs: '2px',
      xs: '4px',
      sm: '6px',
      md: '8px',
      lg: '12px',
      xl: '18px',
      xxl: '24px',
    },
  },
});

I know we have the responsiveFontSizes/enhanceHighContrast precedent, but if these grow it starts to look awkward:

const theme = responsiveFontSizes(
  enhanceHighContrast(
    enhanceDensity(createTheme({ cssVariables: true })),
  ),
);

Makes you wonder does the order of these matter? and whether at some point there could be conflicts if these were applied out of order

As far as I can tell, the only technical benefit of the "enhancer function" API seems to be bundle size 🤔

[siriwatknp]

As far as I can tell, the only technical benefit of the "enhancer function" API seems to be bundle size 🤔

That's the main benefit, the other crucial one is that I don't want the default scale to be opinionated.

[LukasTy]

Overall it looks very nice.
Great direction and the solution looks super clean, especially compared to the initial explorations. 👌

Product asks

• enhanceNormalDensity is a naming hazard. "Normal" reads as a no-op, but it reflows onto the normalized scale and can diff against the unconfigured render. Either make it pixel-identical or rename it. Related: the X Data Grid already ships density: 'compact' | 'standard' | 'comfortable' -- aligning the vocabulary (Standard, Comfortable) keeps the product family coherent.
  In general, do we need the 3 densities besides the default one?
• Enhancer composition (@mj12albert's concern): answer with guarantees rather than a redesign -- assert and test that the enhancers are idempotent and order-independent with responsiveFontSizes/enhanceHighContrast. A compose helper can come later without breaking anything.
• Benchmark the applied cost. Zero cost when unused is proven; the unmeasured number is style-generation cost and emitted CSS weight when a preset is applied (every covered (variant, size) cell x slots). One benchmark line in the RFC would settle whether emission volume needs a budget.
• MUI X follow-up. What plan do you see to achieve this for MUI X packages?
  I assume we'll need similar helper styling functions (possibly per package?) to handle it there.
  Or do you have other ideas?

Prototype spot-check (#48749) against the RFC text

I went through the prototype diff claim by claim. The architecture holds up: the --mui-density-* scale rides the theme's own vars channel exactly as described (including the no-CssBaseline and static-theme paths, unit-tested), slot/portal emission rules are followed (Tooltip tooltip/popper/arrow, Autocomplete listbox), base inheritance works as written (input padding on MuiInputBase, no MuiButtonBase emissions anywhere), the --_* var inventory matches the named set exactly, and the public surface is the three presets with no options. Since "the emitted overrides + per-component mapping are what this RFC signs off", the remaining text-vs-code mismatches are worth fixing (in the RFC or in the emissions) before sign-off:

• Requirement 5's type/icon story doesn't match the implementation. (a) The named per-size examples don't reflow: Button/ToggleButton emissions are padding-only; compact instead moves the shared typography.button token 14px -> 13px, which collapses small == medium (comfort collapses medium == large at 15px) -- "Button small != large, ToggleButton 13/15" never moves per size. (b) The "no size-carrying prop -> type frozen" rule is deliberately broken by compact: Tooltip 11px -> 10px, Tab base 14px -> 13px, AccordionDetails pinned at 0.875rem (all marked "compact-only type" in code comments). (c) Icons aren't fed by the typography config: SvgIcon 18/20/30 are inline literals (compact-only), Chip icons calc off --_height, and the "Rating star 18/24/30" example has no implementation. The prototype's behavior looks like a defensible design -- it's just not the one requirement 5 describes, so I'd rewrite that paragraph around what the code actually does.
• Staged-coverage corrections. MuiIconButton and MuiRating appear nowhere in the diff despite both being listed as "draft emissions staged in the presets". And SvgIcon -- one of the 10 verified families -- reflows only under compact (normal/comfort intentionally emit nothing); the coverage claim should say so.
• The guard net is narrower than described. Readback parity value-checks only the surfaced playground subset (registeredFieldIds, with function-matcher rows skipped except one Tab case) -- staged rows in the ~220-row table are never checked against the presets. The generated table header says "CI diffs this file" but no CI job re-runs density:codegen. The PR body's "compact/comfort reflow captures" for density:shot is off twice: the actual levels are dense/loose (review-only), and they set per-component tokens from the [material-ui] CSS-var density adapter experiment #48624 architecture that nothing in this emission-based PR consumes, so they cannot show reflow. Before the rollout leans on these guards, I'd wire the codegen freshness check into CI, extend parity to the full table, and refresh the harness -- ideally making the generated table the canonical mapping dataset (presets verified against it in full, coverage reports derived from it).
• "Zero component-source changes" has one undisclosed exception. formControlLabelClasses.ts gains a labelPlacementEnd key the presets need for a :has() selector. It's behavior-neutral (the DOM class was already emitted at runtime), but the absolute claim and its checked box should disclose it.
• Wording drift to fix in one pass. "Emits ONE private CSS var" vs the 2-3 seed vars the RFC itself enumerates (filled/standard/Autocomplete); the outlined bridge names --_shrinkY, but shrink is never density-driven for outlined (hardcoded master literal, per the code's own comment); --_height/--_arrowSize/--_restY/--_shrinkY aren't component-prefixed despite decision 3; tag values ride the tag slot, not root; a few spacing seeds are tuned raw px (--_filledInputPadTop: 20px, frozen --_inputMarginTop: 16px) against requirement 5's absolute "spacing off the shared scale".
• Housekeeping. The two ADRs are referenced from the RFC and from in-PR files (harness README, playwright config) but exist only on the [material-ui] CSS-var density adapter experiment #48624 branch; the playground export help text says to render <CssBaseline /> "so the density variables materialise", contradicting the mechanism, the exported file's own header, and the tests; buttons.a11y.json looks like an unrelated stray change; the public DensityScale type export contradicts densityScale.ts's own "not re-exported from the barrel" comment -- align one or the other.