[button] Enable buttons to remain focusable when disabled

docs/data/material/components/buttons/LoadingButtonsTransition.js

@@ -33,6 +33,7 @@ export default function LoadingButtonsTransition() {
           loading={loading}
           variant="outlined"
           disabled
+          focusableWhenDisabled
         >
           Disabled
         </Button>
@@ -42,6 +43,7 @@ export default function LoadingButtonsTransition() {
           loading={loading}
           loadingIndicator="Loading…"
           variant="outlined"
+          focusableWhenDisabled
         >
           Fetch data
         </Button>
@@ -52,6 +54,7 @@ export default function LoadingButtonsTransition() {
           loading={loading}
           loadingPosition="end"
           variant="contained"
+          focusableWhenDisabled
         >
           Send
         </Button>
@@ -63,19 +66,27 @@ export default function LoadingButtonsTransition() {
           loadingPosition="start"
           startIcon={<SaveIcon />}
           variant="contained"
+          focusableWhenDisabled
         >
           Save
         </Button>
       </Box>
       <Box sx={{ '& > button': { m: 1 } }}>
-        <Button onClick={handleClick} loading={loading} variant="outlined" disabled>
+        <Button
+          onClick={handleClick}
+          loading={loading}
+          variant="outlined"
+          disabled
+          focusableWhenDisabled
+        >
           Disabled
         </Button>
         <Button
           onClick={handleClick}
           loading={loading}
           loadingIndicator="Loading…"
           variant="outlined"
+          focusableWhenDisabled
         >
           Fetch data
         </Button>
@@ -85,6 +96,7 @@ export default function LoadingButtonsTransition() {
           loading={loading}
           loadingPosition="end"
           variant="contained"
+          focusableWhenDisabled
         >
           Send
         </Button>
@@ -95,6 +107,7 @@ export default function LoadingButtonsTransition() {
           loadingPosition="start"
           startIcon={<SaveIcon />}
           variant="contained"
+          focusableWhenDisabled
         >
           Save
         </Button>

docs/data/material/components/buttons/LoadingButtonsTransition.tsx

@@ -33,6 +33,7 @@ export default function LoadingButtonsTransition() {
           loading={loading}
           variant="outlined"
           disabled
+          focusableWhenDisabled
         >
           Disabled
         </Button>
@@ -42,6 +43,7 @@ export default function LoadingButtonsTransition() {
           loading={loading}
           loadingIndicator="Loading…"
           variant="outlined"
+          focusableWhenDisabled
         >
           Fetch data
         </Button>
@@ -52,6 +54,7 @@ export default function LoadingButtonsTransition() {
           loading={loading}
           loadingPosition="end"
           variant="contained"
+          focusableWhenDisabled
         >
           Send
         </Button>
@@ -63,19 +66,27 @@ export default function LoadingButtonsTransition() {
           loadingPosition="start"
           startIcon={<SaveIcon />}
           variant="contained"
+          focusableWhenDisabled
         >
           Save
         </Button>
       </Box>
       <Box sx={{ '& > button': { m: 1 } }}>
-        <Button onClick={handleClick} loading={loading} variant="outlined" disabled>
+        <Button
+          onClick={handleClick}
+          loading={loading}
+          variant="outlined"
+          disabled
+          focusableWhenDisabled
+        >
           Disabled
         </Button>
         <Button
           onClick={handleClick}
           loading={loading}
           loadingIndicator="Loading…"
           variant="outlined"
+          focusableWhenDisabled
         >
           Fetch data
         </Button>
@@ -85,6 +96,7 @@ export default function LoadingButtonsTransition() {
           loading={loading}
           loadingPosition="end"
           variant="contained"
+          focusableWhenDisabled
         >
           Send
         </Button>
@@ -95,6 +107,7 @@ export default function LoadingButtonsTransition() {
           loadingPosition="start"
           startIcon={<SaveIcon />}
           variant="contained"
+          focusableWhenDisabled
         >
           Save
         </Button>

docs/data/material/components/buttons/LoadingIconButton.js

@@ -13,7 +13,11 @@ export default function LoadingIconButton() {
   });
   return (
     <Tooltip title="Click to see loading">
-      <IconButton onClick={() => setLoading(true)} loading={loading}>
+      <IconButton
+        onClick={() => setLoading(true)}
+        loading={loading}
+        focusableWhenDisabled
+      >
         <ShoppingCartIcon />
       </IconButton>
     </Tooltip>

docs/data/material/components/buttons/LoadingIconButton.tsx

@@ -13,7 +13,11 @@ export default function LoadingIconButton() {
   });
   return (
     <Tooltip title="Click to see loading">
-      <IconButton onClick={() => setLoading(true)} loading={loading}>
+      <IconButton
+        onClick={() => setLoading(true)}
+        loading={loading}
+        focusableWhenDisabled
+      >
         <ShoppingCartIcon />
       </IconButton>
     </Tooltip>

docs/data/material/components/buttons/LoadingIconButton.tsx.preview

@@ -1,5 +1,9 @@
 <Tooltip title="Click to see loading">
-  <IconButton onClick={() => setLoading(true)} loading={loading}>
+  <IconButton
+    onClick={() => setLoading(true)}
+    loading={loading}
+    focusableWhenDisabled
+  >
     <ShoppingCartIcon />
   </IconButton>
 </Tooltip>

docs/data/material/components/buttons/buttons.md

@@ -21,6 +21,10 @@ Buttons communicate actions that users can take. They are typically placed throu
 
 {{"component": "@mui/internal-core-docs/ComponentLinkHeader"}}
 
+## Usage guidelines
+
+- **Keep disabled buttons discoverable**: Use `focusableWhenDisabled` to keep disabled `Button`s and `IconButton`s in the tab order. This makes unavailable actions discoverable to screen reader users while still preventing activation.
+
 ## Basic button
 
 The `Button` comes with three variants: text (default), contained, and outlined.
@@ -115,6 +119,7 @@ Use `color` prop to apply theme color palette to component.
 ### Loading
 
 Starting from v6.4.0, use `loading` prop to set icon buttons in a loading state and disable interactions.
+For icon buttons that enter a loading state after being clicked, set `focusableWhenDisabled` to retain focus and maintain tab order while disabled.
 
 {{"demo": "LoadingIconButton.js"}}
 
@@ -133,6 +138,7 @@ To create a file upload button, turn the button into a label using `component="l
 ## Loading
 
 Starting from v6.4.0, use the `loading` prop to set buttons in a loading state and disable interactions.
+For buttons that enter a loading state after being clicked, set `focusableWhenDisabled` to retain focus and maintain tab order while disabled.
 
 {{"demo": "LoadingButtons.js"}}
 
@@ -191,23 +197,31 @@ Here is a [more detailed guide](/material-ui/integrations/routing/#button).
 
 ### Cursor not-allowed
 
-The ButtonBase component sets `pointer-events: none;` on disabled buttons, which prevents the appearance of a disabled cursor.
+The ButtonBase component sets `pointer-events: none;` on disabled buttons by default, which prevents the appearance of a disabled cursor.
 
 If you wish to use `not-allowed`, you have two options:
 
-1. **CSS only**. You can remove the pointer-events style on the disabled state of the `<button>` element:
+1. **CSS only**. You can remove the pointer-events style on the disabled state:
 
 ```css
-.MuiButtonBase-root:disabled {
+.MuiButtonBase-root.Mui-disabled {
   cursor: not-allowed;
   pointer-events: auto;
 }
 ```
 
-However:
+For disabled `Button` and `IconButton` components that need to trigger a Tooltip, use the `focusableWhenDisabled` prop instead:
+
+```jsx
+<Tooltip title="You don't have permission to do this">
+  <Button disabled focusableWhenDisabled>
+    Disabled
+  </Button>
+</Tooltip>
+```
 
-- You should add `pointer-events: none;` back when you need to display [tooltips on disabled elements](/material-ui/react-tooltip/#disabled-elements).
-- The cursor won't change if you render something other than a button element, for instance, a link `<a>` element.
+The prop keeps disabled buttons focusable and hoverable while preventing activation.
+Disabled links remain non-focusable and pointer-inert.
 
 2. **DOM change**. You can wrap the button:
 

docs/data/material/components/snackbars/snackbars.md

@@ -122,7 +122,7 @@ Note that notistack prevents Snackbars from being [closed by pressing <kbd class
 
 ## Accessibility
 
-The user should be able to dismiss Snackbars by pressing <kbd class="key">Escape</kbd>. If there are multiple instances appearing at the same time and you want <kbd class="key">Escape</kbd> to dismiss only the oldest one that's currently open, call `event.preventDefault` in the `onClose` prop.
+The user should be able to dismiss Snackbars by pressing <kbd class="key">Escape</kbd>. If there are multiple instances appearing at the same time and you want <kbd class="key">Escape</kbd> to dismiss only the oldest one that's currently open, call `event.preventDefault()` in the `onClose` prop.
 
 ```jsx
 export default function MyComponent() {
@@ -133,9 +133,11 @@ export default function MyComponent() {
       <Snackbar
         open={open}
         onClose={(event, reason) => {
-          // `reason === 'escapeKeyDown'` if `Escape` was pressed
           setOpen(false);
-          // call `event.preventDefault` to only close one Snackbar at a time.
+          if (reason === 'escapeKeyDown') {
+            // Only close one Snackbar at a time.
+            event.preventDefault();
+          }
         }}
       />
       <Snackbar open={open} onClose={() => setOpen(false)} />

docs/pages/material-ui/api/button.json

@@ -15,6 +15,7 @@
     "disableFocusRipple": { "type": { "name": "bool" }, "default": "false" },
     "disableRipple": { "type": { "name": "bool" }, "default": "false" },
     "endIcon": { "type": { "name": "node" } },
+    "focusableWhenDisabled": { "type": { "name": "bool" }, "default": "false" },
     "fullWidth": { "type": { "name": "bool" }, "default": "false" },
     "href": { "type": { "name": "string" } },
     "loading": { "type": { "name": "bool" }, "default": "null" },

docs/pages/material-ui/api/icon-button.json

@@ -19,6 +19,7 @@
       },
       "default": "false"
     },
+    "focusableWhenDisabled": { "type": { "name": "bool" }, "default": "false" },
     "loading": { "type": { "name": "bool" }, "default": "null" },
     "loadingIndicator": {
       "type": { "name": "node" },

docs/translations/api-docs/button/button.json

@@ -18,6 +18,9 @@
       "description": "If <code>true</code>, the ripple effect is disabled.<br>⚠️ Without a ripple there is no styling for :focus-visible by default. Be sure to highlight the element by applying separate styles with the <code>.Mui-focusVisible</code> class."
     },
     "endIcon": { "description": "Element placed after the children." },
+    "focusableWhenDisabled": {
+      "description": "If <code>true</code>, allows a disabled component to retain keyboard and programmatic focusability while preventing activation. Disabled links remain non-focusable."
+    },
     "fullWidth": {
       "description": "If <code>true</code>, the button will take up the full width of its container."
     },

docs/translations/api-docs/icon-button/icon-button.json

@@ -16,6 +16,9 @@
     "edge": {
       "description": "If given, uses a negative margin to counteract the padding on one side (this is often helpful for aligning the left or right side of the icon with content above or below, without ruining the border size and shape)."
     },
+    "focusableWhenDisabled": {
+      "description": "If <code>true</code>, allows a disabled component to retain keyboard and programmatic focusability while preventing activation. Disabled links remain non-focusable."
+    },
     "loading": {
       "description": "If <code>true</code>, the loading indicator is visible and the button is disabled. If <code>true | false</code>, the loading wrapper is always rendered before the children to prevent <a href=\"https://github.com/mui/material-ui/issues/27853\">Google Translation Crash</a>."
     },

packages/mui-material/src/Button/Button.d.ts

@@ -52,6 +52,12 @@ export interface ButtonOwnProps {
    * Element placed after the children.
    */
   endIcon?: React.ReactNode;
+  /**
+   * If `true`, allows a disabled component to retain keyboard and programmatic focusability while preventing activation.
+   * Disabled links remain non-focusable.
+   * @default false
+   */
+  focusableWhenDisabled?: boolean | undefined;
   /**
    * If `true`, the button will take up the full width of its container.
    * @default false

packages/mui-material/src/Button/Button.js

@@ -104,6 +104,7 @@ const ButtonRoot = styled(ButtonBase, {
       padding: '6px 16px',
       border: 0,
       borderRadius: (theme.vars || theme).shape.borderRadius,
+      '--Button-focusRingColor': (theme.vars || theme).palette.primary.main,
       ...getTransitionStyles(theme, ['background-color', 'box-shadow', 'border-color', 'color'], {
         duration: theme.transitions.duration.short,
       }),
@@ -114,6 +115,15 @@ const ButtonRoot = styled(ButtonBase, {
         color: (theme.vars || theme).palette.action.disabled,
       },
       variants: [
+        {
+          props: { focusableWhenDisabled: true },
+          style: {
+            [`&.${buttonClasses.disabled}.${buttonClasses.focusVisible}`]: {
+              outline: '2px solid var(--Button-focusRingColor)',
+              outlineOffset: 2,
+            },
+          },
+        },
         {
           props: { variant: 'contained' },
           style: {
@@ -174,8 +184,9 @@ const ButtonRoot = styled(ButtonBase, {
               ),
               '--variant-containedColor': (theme.vars || theme).palette[color].contrastText,
               '--variant-containedBg': (theme.vars || theme).palette[color].main,
+              '--Button-focusRingColor': (theme.vars || theme).palette[color].main,
               '@media (hover: hover)': {
-                '&:hover': {
+                [`&:hover:not(.${buttonClasses.disabled})`]: {
                   '--variant-containedBg': (theme.vars || theme).palette[color].dark,
                   '--variant-textBg': theme.alpha(
                     (theme.vars || theme).palette[color].main,
@@ -200,8 +211,9 @@ const ButtonRoot = styled(ButtonBase, {
             '--variant-containedBg': theme.vars
               ? theme.vars.palette.Button.inheritContainedBg
               : inheritContainedBackgroundColor,
+            '--Button-focusRingColor': (theme.vars || theme).palette.text.primary,
             '@media (hover: hover)': {
-              '&:hover': {
+              [`&:hover:not(.${buttonClasses.disabled})`]: {
                 '--variant-containedBg': theme.vars
                   ? theme.vars.palette.Button.inheritContainedHoverBg
                   : inheritContainedHoverBackgroundColor,
@@ -509,6 +521,7 @@ const Button = React.forwardRef(function Button(inProps, ref) {
     disableElevation = false,
     disableFocusRipple = false,
     endIcon: endIconProp,
+    focusableWhenDisabled = false,
     focusVisibleClassName,
     fullWidth = false,
     id: idProp,
@@ -521,7 +534,6 @@ const Button = React.forwardRef(function Button(inProps, ref) {
     variant = 'text',
     ...other
   } = props;
-
   const loadingId = useId(idProp);
   const loadingIndicator = loadingIndicatorProp ?? (
     <CircularProgress aria-labelledby={loadingId} color="inherit" size={16} />
@@ -597,6 +609,7 @@ const Button = React.forwardRef(function Button(inProps, ref) {
       type={type}
       id={loading ? loadingId : idProp}
       {...other}
+      focusableWhenDisabled={focusableWhenDisabled === true}
       classes={forwardedClasses}
     >
       {startIcon}
@@ -667,6 +680,12 @@ Button.propTypes /* remove-proptypes */ = {
    * Element placed after the children.
    */
   endIcon: PropTypes.node,
+  /**
+   * If `true`, allows a disabled component to retain keyboard and programmatic focusability while preventing activation.
+   * Disabled links remain non-focusable.
+   * @default false
+   */
+  focusableWhenDisabled: PropTypes.bool,
   /**
    * @ignore
    */