如何为MUI Autocomplete选项列表添加自定义滚动条

MUI Autocomplete 的下拉选项列表通过 ListboxComponent 插槽支持自定义容器替换，只需要将默认带原生滚动的容器替换为包裹了 react-custom-scrollbars-2 的自定义组件，即可统一滚动条样式，不影响原有选项选中、异步加载、键盘导航等所有原生功能。

实现步骤 #

• 确认项目已安装 react-custom-scrollbars-2 依赖
• 编写自定义Listbox包装组件，使用React.forwardRef透传ref和所有无障碍属性，内部嵌套Scrollbars组件作为滚动容器
• 将自定义组件传入Autocomplete的ListboxComponent属性
• 重置默认Listbox的原生滚动、高度、内边距样式，避免出现双滚动条、高度错位问题
• 按需调整滚动条滑块、轨道样式，和项目全局自定义滚动条样式保持一致

完整代码示例 #

import React from 'react';
import { Autocomplete, TextField } from '@mui/material';
import { Scrollbars } from 'react-custom-scrollbars-2';

// 自定义滚动条容器，兼容MUI Listbox要求的属性和ref
const CustomScrollListbox = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLElement>>(
  (props, ref) => {
    const { children, ...restProps } = props;
    return (
      <div ref={ref} {...restProps}>
        <Scrollbars
          autoHide
          style={{
            height: '100%',
            maxHeight: '40vh' // 和MUI默认下拉列表最大高度保持一致
          }}
          // 自定义滚动条滑块样式，可根据全局设计规范调整
          renderThumbVertical={({ style, ...thumbProps }) => (
            <div
              {...thumbProps}
              style={{
                ...style,
                width: 6,
                borderRadius: 3,
                backgroundColor: 'rgba(0, 0, 0, 0.2)',
                right: 4,
              }}
            />
          )}
        >
          {children}
        </Scrollbars>
      </div>
    );
  }
);

// 业务中使用，支持异步请求场景
export default function ScrollStyledAutocomplete() {
  return (
    <Autocomplete
      // 原有业务属性保持不变，比如options、loading、onInputChange异步逻辑等
      options={[]}
      ListboxComponent={CustomScrollListbox}
      // 重置默认Listbox样式，避免冲突
      ListboxProps={{
        style: {
          padding: 0,
          maxHeight: 'unset',
          overflow: 'unset'
        }
      }}
      renderInput={(params) => (
        <TextField {...params} label="搜索选项" />
      )}
    />
  );
}

常见问题处理 #

• 出现双滚动条：检查是否给ListboxProps设置了overflow: 'unset'，确认没有给外层容器额外设置overflow属性
• 下拉定位偏移、选项无法点击：必须用React.forwardRef将ref透传到Listbox的根容器，不要直接把Scrollbars组件传给ListboxComponent
• 高度异常：Scrollbars的maxHeight值和MUI默认的40vh对齐即可，不要给外层Listbox设置固定高度
• 异步加载选项后滚动条不更新：Scrollbars会自动监听子元素高度变化，不需要手动调用更新方法，如果出现异常可给Scrollbars组件加key绑定选项长度触发重渲染

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