[circularprogress][linearprogress] Improve accessibility by silviuaavram · Pull Request #48172 · mui/material-ui

silviuaavram · 2026-04-01T15:02:59Z

I have followed (at least) the PR section of the contributing guide.

Closes #48179.
Closes #39072.

LinearProgress

add min and max props
add non-production checks for when value and bufferValue is not between the min and max values
add non-production checks for passing min and max with indeterminate / query variants
safeguard against calculating style when min >= max, show 0 progress visually
change label docs example to include both label and value label
add docs example to illustrate aria-valuetext
docs example for missing query variant.

CircularProgress

add min and max props
non-production check for value when not in bounds
add non-production checks for passing min and max with indeterminate / query variants
safeguard against calculating style when min >= max, show empty circle visually
docs example to illustrate custom scales (min and max usage)

mui-bot · 2026-04-01T15:04:06Z

Netlify deploy preview

docs/data/material/components/progress/progress.md

Bundle size report

Bundle	Parsed size	Gzip size
@mui/material	🔺+136B^(+0.03%)	🔺+71B^(+0.05%)
@mui/lab	0B^(0.00%)	0B^(0.00%)
@mui/system	0B^(0.00%)	0B^(0.00%)
@mui/utils	0B^(0.00%)	0B^(0.00%)

Details of bundle changes

Generated by 🚫 dangerJS against 73fd6d6

Copilot

Pull request overview

Improves accessibility and flexibility of LinearProgress and CircularProgress by introducing configurable value ranges (minValue/maxValue), adding dev-time range validation, and updating documentation/examples to better demonstrate accessible labeling patterns.

Changes:

Add minValue/maxValue props to Linear/Circular progress and update determinate/buffer calculations to use the custom range.
Add/extend tests for RTL determinate behavior and custom range + dev warnings.
Update docs and API descriptions with new demos (custom scale, aria-valuetext, query variant) and revised labeling example.

Reviewed changes

Copilot reviewed 22 out of 24 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
packages/mui-material/src/LinearProgress/LinearProgress.js	Implements `minValue`/`maxValue` handling and dev warnings for LinearProgress.
packages/mui-material/src/LinearProgress/LinearProgress.d.ts	Adds TS typings for `minValue`/`maxValue`.
packages/mui-material/src/LinearProgress/LinearProgress.test.js	Adds RTL determinate coverage and custom range/warning tests.
packages/mui-material/src/CircularProgress/CircularProgress.js	Implements `minValue`/`maxValue` handling and dev warnings for CircularProgress determinate.
packages/mui-material/src/CircularProgress/CircularProgress.d.ts	Adds TS typings for `minValue`/`maxValue`.
packages/mui-material/src/CircularProgress/CircularProgress.test.js	Adds custom range and warning tests for CircularProgress.
docs/translations/api-docs/linear-progress/linear-progress.json	Documents new props in generated API translations.
docs/translations/api-docs/circular-progress/circular-progress.json	Documents new props in generated API translations.
docs/pages/material-ui/api/linear-progress.json	Adds `minValue`/`maxValue` to API page JSON.
docs/pages/material-ui/api/circular-progress.json	Adds `minValue`/`maxValue` to API page JSON.
docs/data/material/components/progress/progress.md	Adds new demos/sections (custom scale, query, `aria-valuetext`) and updates headings/text.
docs/data/material/components/progress/LinearWithValueLabel.tsx	Updates the “with label” demo to use `aria-labelledby` + visible label and value label.
docs/data/material/components/progress/LinearWithValueLabel.js	JS version of the updated “with label” demo.
docs/data/material/components/progress/LinearWithValueLabel.tsx.preview	Updates preview snippet to new component name.
docs/data/material/components/progress/LinearWithAriaValueText.tsx	New demo showing `aria-valuetext` for non-percentage scales.
docs/data/material/components/progress/LinearWithAriaValueText.js	JS version of the new `aria-valuetext` demo.
docs/data/material/components/progress/LinearWithAriaValueText.tsx.preview	Preview snippet for the new `aria-valuetext` demo.
docs/data/material/components/progress/LinearQuery.tsx	New demo for `variant="query"`.
docs/data/material/components/progress/LinearQuery.js	JS version of the new query demo.
docs/data/material/components/progress/LinearQuery.tsx.preview	Preview snippet for the new query demo.
docs/data/material/components/progress/CircularCustomScale.tsx	New demo showing custom scale usage for CircularProgress.
docs/data/material/components/progress/CircularCustomScale.js	JS version of the custom scale demo.
docs/data/material/components/progress/CircularCustomScale.tsx.preview	Preview snippet for the custom scale demo.
docs/data/material/components/progress/CircularWithValueLabel.js	Updates wording to reference `minValue`/`maxValue`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

mj12albert · 2026-04-04T16:12:21Z

+      rootProps['aria-valuemin'] = minValue;
+      rootProps['aria-valuemax'] = maxValue;
+      let transform = ((value - minValue) / (maxValue - minValue)) * 100 - 100;
      if (isRtl) {


Technically a user could pass in identical max and min, causing division by 0, we could add another dev warning when min >= max, e.g. https://github.com/mui/base-ui/blob/d15bc0a4fb82f56f08c16d50cd6a4acc3c5247e5/packages/react/src/slider/root/SliderRoot.tsx#L270-L274

and then no need to handle it here

mapache-salvaje

Docs changes look good! 👍

siriwatknp

Good accessibility improvements overall — min/max props, dev warnings, and new demos are solid additions. A few issues to address:

siriwatknp · 2026-04-07T07:50:04Z

      if (isRtl) {
        transform = -transform;
      }
      inlineStyles.bar1.transform = `translateX(${transform}%)`;


Same division-by-zero issue here. If max === min, ((value - min) / (max - min)) → NaN. Should guard range > 0 before computing transforms, or clamp.

I think this is fine since we already have an error for min>=max, which is obvious developer error

Added a guard for both this one and circular progress

siriwatknp · 2026-04-07T07:50:04Z

+    circleStyle.strokeDashoffset = `${(((max - value) / (max - min)) * circumference).toFixed(3)}px`;
    rootStyle.transform = 'rotate(-90deg)';
+
+    rootProps['aria-valuenow'] = Math.round(value);


Nit: aria-valuemin and aria-valuemax are only set in the determinate branch. Per WAI-ARIA progressbar, aria-valuemin/aria-valuemax are optional when using the default 0-100 range. But when custom min/max are provided by the user for indeterminate (which is ignored here), no warning is emitted. Consider warning if min/max are provided with variant="indeterminate" since they have no effect.

mj12albert · 2026-04-12T18:47:07Z

-      inlineStyles.bar1.transform = `translateX(${transform}%)`;
+      inlineStyles.bar1.transform = range > 0 ? `translateX(${transform}%)` : undefined;
+
+      rootProps['aria-valuenow'] = Math.round(value);


Suggested change

rootProps['aria-valuenow'] = Math.round(value);

rootProps['aria-valuenow'] = value;

Shouldn't round this or it will break when min={0} max={1} value={0.25}

It was like this before my changes, but the comment is relevant. Will change for both!

code-infra-dashboard · 2026-04-14T12:02:33Z

Bundle size

Bundle	Parsed size	Gzip size
@mui/material	🔺+180B^(+0.04%)	🔺+79B^(+0.05%)
@mui/lab	0B^(0.00%)	0B^(0.00%)
@mui/private-theming	0B^(0.00%)	0B^(0.00%)
@mui/system	0B^(0.00%)	0B^(0.00%)
@mui/utils	0B^(0.00%)	0B^(0.00%)

Details of bundle changes

Deploy preview

docs/data/material/components/progress/progress.md

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

mj12albert · 2026-04-14T16:46:41Z

Might be worth adding just a bit more docs and close this issue out as well: #39072

siriwatknp

Adversarial review flagged a few concerns around the new range support. Details inline.

siriwatknp · 2026-04-15T07:36:18Z

        transform = -transform;
      }
-      inlineStyles.bar2.transform = `translateX(${transform}%)`;
+      inlineStyles.bar2.transform = range > 0 ? `translateX(${transform}%)` : undefined;


[high] Fails open on invalid range.

When min >= max, the inline transform is set to undefined, but the base bar styling renders both bars at full width — so production builds display a completed bar for invalid input. That turns bad backend/config data into a user-visible false-success state, which is the exact class of bug these props should surface.

Recommendation: fail closed instead of open. Either clamp to an empty state (translateX(-100%) / equivalent), or skip rendering the determinate fill entirely when the range is invalid, while still logging the validation error in development.

See https://stackblitz.com/edit/poztqgw3?file=src%2FDemo.tsx

Added the translateX(-100%) fallback when min > max

siriwatknp

Thanks for the fixes — fail-closed behavior and error prefix look good. One minor doc nit from re-review.

Copilot

Pull request overview

Copilot reviewed 22 out of 24 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-15T10:20:16Z

+    it('should warn if the value is out of range', () => {
+      expect(() => {
+        render(<LinearProgress variant="determinate" value={-1} min={0} max={10} />);
+      }).toErrorDev([
+        'MUI: The min, max, and value props in LinearProgress should be numbers where min < max and min <= value <= max. Received min=0, max=10, value=-1.',


Test name says "should warn" but the assertion expects console.error via toErrorDev. Rename the test (or change the expectation) so the wording matches the actual behavior being verified.

silviuaavram marked this pull request as ready for review April 2, 2026 07:59

silviuaavram requested review from Copilot, mapache-salvaje, mj12albert, mnajdova and siriwatknp April 2, 2026 07:59

Copilot started reviewing on behalf of silviuaavram April 2, 2026 07:59 View session

Copilot AI reviewed Apr 2, 2026

View reviewed changes

mj12albert reviewed Apr 4, 2026

View reviewed changes

silviuaavram force-pushed the feat/progress-accessibility branch from 2e8c17d to a91d06e Compare April 6, 2026 07:48

silviuaavram added needs cherry-pick The PR should be cherry-picked to master after merge. v7.x labels Apr 6, 2026

mapache-salvaje reviewed Apr 6, 2026

View reviewed changes

mj12albert approved these changes Apr 7, 2026

View reviewed changes

Comment thread docs/data/material/components/progress/progress.md Outdated

Comment thread packages/mui-material/src/CircularProgress/CircularProgress.test.js

siriwatknp requested changes Apr 7, 2026

View reviewed changes

silviuaavram force-pushed the feat/progress-accessibility branch from dba6fe7 to fac9022 Compare April 8, 2026 12:34

mj12albert reviewed Apr 12, 2026

View reviewed changes

Comment thread packages/mui-material/src/CircularProgress/CircularProgress.js Outdated

Comment thread packages/mui-material/src/LinearProgress/LinearProgress.js Outdated

Comment thread docs/data/material/components/progress/LinearWithValueLabel.tsx Outdated

mj12albert reviewed Apr 12, 2026

View reviewed changes

silviuaavram force-pushed the feat/progress-accessibility branch from ac8c332 to 4a3d781 Compare April 14, 2026 11:23

silviuaavram added 5 commits April 14, 2026 14:58

[circularprogress][linearprogress] Improve accessibility

aeca3d7

add linear query

c1b867a

also add visible label to linear

b18110c

update proptypes

0dafb88

linear with aria-valuetext

c375981

silviuaavram added 7 commits April 14, 2026 14:58

only warn when min or max are provided with wrong variant

7ed9b3e

regex for dashoffset too

165ac99

fix error messages

656d608

remove not needed margin

ab46e75

fix the value default with min

eed6fbe

remove rounding of value

5704bb0

fix lint

6a1b88f

silviuaavram force-pushed the feat/progress-accessibility branch from 73fd6d6 to 6a1b88f Compare April 14, 2026 11:59

silviuaavram added 4 commits April 14, 2026 15:15

update jsdoc

8e97de0

fix again jsdoc

4f637da

fix jsdoc in examples

843ead2

update docs

2e29524

siriwatknp reviewed Apr 15, 2026

View reviewed changes

silviuaavram added 4 commits April 15, 2026 11:00

updates for docs page

b36a42d

add MUI error prefix

1933116

safer fallbacks for min > max

6972aba

fix the other test

c19fc27

siriwatknp reviewed Apr 15, 2026

View reviewed changes

Comment thread packages/mui-material/src/CircularProgress/CircularProgress.js Outdated

siriwatknp approved these changes Apr 15, 2026

View reviewed changes

fix jsdoc min reference

5f8524a

silviuaavram requested a review from Copilot April 15, 2026 10:15

Copilot started reviewing on behalf of silviuaavram April 15, 2026 10:16 View session

docs:api

f93b11f

Copilot AI reviewed Apr 15, 2026

View reviewed changes

silviuaavram removed v7.x needs cherry-pick The PR should be cherry-picked to master after merge. labels Apr 15, 2026

silviuaavram merged commit 529b113 into mui:master Apr 15, 2026
25 checks passed

silviuaavram deleted the feat/progress-accessibility branch April 15, 2026 10:29

	rootProps['aria-valuenow'] = Math.round(value);
	rootProps['aria-valuenow'] = value;

Uh oh!

Conversation

silviuaavram commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

LinearProgress

CircularProgress

Uh oh!

mui-bot commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Netlify deploy preview

Bundle size report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mapache-salvaje left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

siriwatknp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

code-infra-dashboard bot commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle size

Deploy preview

Uh oh!

mj12albert commented Apr 14, 2026

Uh oh!

siriwatknp left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

silviuaavram commented Apr 1, 2026 •

edited

Loading

mui-bot commented Apr 1, 2026 •

edited

Loading

code-infra-dashboard bot commented Apr 14, 2026 •

edited

Loading