Chakra UI自定义主题无法触发自定义变体自动补全问题求助

问题根源 #

Chakra UI的默认TypeScript类型声明不会自动识别你新增的自定义变体，satisfies ThemeOverride仅做类型校验，不会扩展全局类型；Chakra CLI生成的类型通常针对默认主题，无法自动适配手动添加的自定义变体。

解决步骤 #

1. 创建自定义类型声明文件 #

在项目src目录下新建types/chakra-ui.d.ts文件，用于扩展Chakra的类型定义：

import { ComponentStyleConfig } from '@chakra-ui/react';

// 列出所有你自定义的Text变体名称
type CustomTextVariants = 'custom-heading' | 'custom-body' | 'your-custom-variant';

declare module '@chakra-ui/react' {
  // 扩展Text组件的变体类型
  interface ComponentThemeConfig {
    Text: ComponentStyleConfig & {
      variants?: Record<CustomTextVariants, any>;
    };
  }

  // 如果你的变体是通过全局textStyles定义的，扩展这个接口
  interface Theme {
    textStyles?: Record<CustomTextVariants, any>;
  }
}

2. 确保TypeScript识别声明文件 #

检查项目根目录的tsconfig.json，确认include数组包含类型文件路径：

{
  "include": [
    "src/**/*",
    "src/types/**/*" // 确保该路径存在
  ]
}

3. 重新约束主题类型（可选但推荐） #

定义主题时用扩展后的类型做约束，确保变体名称和类型声明一致：

import { extendTheme, ThemeOverride } from '@chakra-ui/react';

const extendedConfig: ThemeOverride = {
  components: {
    Text: {
      variants: {
        'custom-heading': {
          fontSize: '2xl',
          fontWeight: 'bold',
          color: 'blue.600',
        },
        'custom-body': {
          fontSize: 'md',
          lineHeight: '1.6',
          color: 'gray.700',
        },
      },
    },
  },
};

const myTheme = extendTheme(extendedConfig);

export default myTheme;

4. 重启TypeScript服务 #

修改类型声明后，重启编辑器的TS语言服务（比如VSCode按Ctrl+Shift+P选择"TypeScript: Restart TS Server"），让新类型生效。

此时再使用<Text variant="">时，就能看到自定义变体的自动补全提示。

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