TypeScript error "colors does not exist in type 'Partial<ThemeObject<DefaultThemeGroupIds>>'" when extending theme in extendTailwindMerge

[JoelDev16]

🐛 Bug Report

Description

When using extendTailwindMerge to extend theme with custom colors and spacing, TypeScript throws compilation errors during build, even though the configuration works correctly in development mode.

Environment

• tailwind-merge version: 2.6.0
• TypeScript version: 5.x
• Next.js version: 15.3.2
• tailwindcss version: 3.x
• Build tool: Next.js build
• OS: Windows 11

Steps to Reproduce

1. Create a tailwind-merge configuration with extended theme:

import { extendTailwindMerge } from "tailwind-merge";

const twMerge = extendTailwindMerge({
  extend: {
    theme: {
      colors: [
        "primary",
        "tin-grey",
        "lead-grey",
        "blue-grey",
        "state",
        "error",
        "warning", 
        "success",
        "selected",
      ],
    },
  },
});

2. Run production build: npm run build

Expected Behavior

The build should complete successfully without TypeScript errors, as the configuration is valid according to the documentation.

Actual Behavior

Build fails with TypeScript compilation error: Object literal may only specify known properties, but 'colors' does not exist in type 'Partial<ThemeObject>'. Did you mean to write 'color'?

Additional Context

• Development mode works fine - no errors during npm run dev
• Build mode fails - TypeScript strict checking during production build
• The error alternates between suggesting colors vs color depending on which one is used
• This appears to be a TypeScript definition issue where the theme extension types don't match the actual runtime behavior

Workaround Found

Instead of extending theme, override existing classGroups directly:

const twMerge = extendTailwindMerge({
  extend: {
    classGroups: {
      // Override existing groups instead of extending theme
      "bg-color": ["primary", "tin-grey", "lead-grey", "blue-grey", "state", "error", "warning", "success", "selected"],
      "text-color": ["primary", "tin-grey", "lead-grey", "blue-grey", "state", "error", "warning", "success", "selected"],
    },
  },
});

Questions

1. Is extending theme via theme.colors officially supported?
2. Should the TypeScript definitions be updated to properly support theme extension?
3. Is the workaround above the recommended approach for adding custom theme values?

Related Issues

This seems related to broader TypeScript compatibility issues with theme configuration, similar to:

• Various Stack Overflow discussions about TailwindCSS + TypeScript type issues

---

Would appreciate clarification on the correct approach for extending themes with TypeScript support. Thank you! 🙏

[dcastil]

Hey @JoelDev16! 👋

Sorry for the long wait, looks like I missed a bunch of notifications.

The TypeScript setup is restricting use of extendTailwindMerge to existing class groups to prevent typos. You can explicitly state your new groups and they'll get allowed by passing them as a generic type argument to extendTailwindMerge.

You can read more about this in https://github.com/dcastil/tailwind-merge/blob/v3.3.1/docs/configuration.md#typescript-types-for-extendtailwindmerge.