如何修改MUI Stepper组件的图标颜色样式

问题背景 #

需要将Stepper步进器的图标默认效果调整为自定义配色样式，直接通过.Mui-active、.Mui-completed、.Mui-disabled类选择器编写的自定义样式无法生效，可通过对应在线Demo复现问题。
参考图1：默认Stepper图标效果
参考图2：目标Stepper图标样式

失效原因 #

自定义样式不生效的核心问题是选择器命中层级错误：Stepper的状态类是挂载在内部StepIcon组件根节点上的，直接在Stepper外层容器上匹配状态类，既无法穿透到内部图标元素，优先级也低于MUI组件的默认内置样式，自然无法覆盖。

实现方案 #

单组件快速修改 #

直接给StepLabel组件传入StepIconProps，定向匹配StepIcon内部元素设置样式即可，示例代码如下：

import { Stepper, Step, StepLabel } from '@mui/material';

// 对应Stepper渲染部分
<Stepper activeStep={activeStep} nonLinear>
  {steps.map((label, index) => (
    <Step key={label}>
      <StepLabel
        StepIconProps={{
          sx: {
            // 待完成默认状态
            '&.MuiStepIcon-root': {
              color: '#e5e7eb',
              '& .MuiStepIcon-text': {
                fill: '#6b7280'
              }
            },
            // 当前激活步骤状态
            '&.Mui-active': {
              color: '#2563eb !important',
              '& .MuiStepIcon-text': {
                fill: '#ffffff !important'
              }
            },
            // 已完成步骤状态
            '&.Mui-completed': {
              color: '#16a34a !important',
              '& .MuiStepIcon-text': {
                fill: '#ffffff !important'
              }
            }
          }
        }}
      >
        {label}
      </StepLabel>
    </Step>
  ))}
</Stepper>

代码中的色值可以直接替换为参考图2对应的配色，即可完全匹配目标效果。

全局统一样式 #

如果项目内所有Stepper都需要使用这套配色，直接在MUI主题配置中覆写MuiStepIcon的默认样式即可，无需在每个组件单独编写样式：

import { createTheme } from '@mui/material/styles';

const theme = createTheme({
  components: {
    MuiStepIcon: {
      styleOverrides: {
        root: {
          color: '#e5e7eb',
          '& .MuiStepIcon-text': {
            fill: '#6b7280'
          },
          '&.Mui-active': {
            color: '#2563eb',
            '& .MuiStepIcon-text': {
              fill: '#ffffff'
            }
          },
          '&.Mui-completed': {
            color: '#16a34a',
            '& .MuiStepIcon-text': {
              fill: '#ffffff'
            }
          }
        }
      }
    }
  }
});

将自定义主题通过ThemeProvider包裹在项目根节点，全局所有Stepper都会自动应用这套样式。

提示：如果需要调整已完成状态的对勾图标颜色，可以额外匹配& .MuiStepIcon-completed选择器设置color属性即可。

内容的提问来源于stack exchange，提问作者Abdelkader