Better documentation of overriding default themes

[spl]

Your documentation is great! I'm just a bit confused on how to override certain parts of a default theme.

The section Overriding the default theme currently has this:

To override an option in the default theme, create a theme section in your tailwind.config.js file and add the key you'd like to override.

This will completely replace Tailwind's default configuration for that key, so in the example above none of the default opacity utilities would be generated.

Any keys you do not provide will be inherited from the default theme, so in the above example, the default theme configuration for things like colors, spacing, border radius, background position, etc. would be preserved.

From my brief experimentation (below), I concluded:

1. I'm not sure if it's correct to say that the section would “completely replace” the default.
2. It was not clear how to override default values that one wants undefined.

Here's what I did. I added the @tailwindcss/typography plugin and the following:

// tailwind.config.js
module.exports = {
  theme: {
    typography: {
      default: {
        css: {
          a: {
            background: /* ... */,
            textShadow: /* ... */,
          },
        },
      },
    },
  },
  plugins: [
    require('@tailwindcss/typography'),
  ],
}

I thought the a object would completely replace the .prose a style. But I discovered that .prose a still had text-decoration: underline, which I did not want. First, I tried adding textDecoration: undefined, to the a in the tailwind.config.js above, but that didn't change anything. Then, I added textDecoration: null,, and that seems to have removed the text-decoration.

In conclusion, would you mind updating the documentation with at least some clarifying text on the following?

1. How are the default values are combined with the overrides in the tailwind.config.js?
2. What is the recommended way to undefine a default value?

Thanks!

[simonswiss]

Hi @spl! 👋

The "overriding the default theme" section you mention is describing how the core Tailwind theme is customised. For properties like spacing, borderRadius etc, defining an object inside your theme will completely replace all the available options for that property.

Tailwind's typography plugin is customised a bit differently, and the documentation for that lives on its own repo that I linked to.

Back to the core Tailwind theme, here's an example of replacing vs extending:

module.exports = {
  theme: {
    spacing: {
      2: '0.5rem'
    }
  }
}

will reduce your spacing utilities to one single option, 2.

To add values to the spacing options, you would extend the spacing key in your theme:

module.exports = {
  theme: {
    extend: {
      spacing: {
        'huge': '100rem'
      }
    }
  }
}

This will keep all the default spacing utilities, and add a huge option to the available options.

I hope this answers your questions! 👍

[spl]

@simonswiss Got it. Thank you very much!