主題配置

在你 tailwind.config.js 配置檔中的 theme 部份可以定義只屬於你專案所使用的色板、大小級距、字型、斷點、圓角程度等。

// tailwind.config.js
const colors = require('tailwindcss/colors')

module.exports = {
  theme: {
    screens: {
      sm: '480px',
      md: '768px',
      lg: '976px',
      xl: '1440px',
    },
    colors: {
      gray: colors.coolGray,
      blue: colors.lightBlue,
      red: colors.rose,
      pink: colors.fuchsia,
    },
    fontFamily: {
      sans: ['Graphik', 'sans-serif'],
      serif: ['Merriweather', 'serif'],
    },
    extend: {
      spacing: {
        '128': '32rem',
        '144': '36rem',
      },
      borderRadius: {
        '4xl': '2rem',
      }
    }
  }
}

我們提供了方便的預設主題和一組泛用的數值來幫助你入門， 不過別害怕去改變或者擴充它，我們鼓勵你盡你所能的去客製化出你所需要、最適合你的設計。

主題結構

theme 物件包含了 screens、colors、spacing 之類的 key，以及每個可以客製化的核心插件的 key。

閱讀主題配置準則或是預設主題中主題選項的完整列表。

螢幕

screens 這個 key 能讓你在專案中自訂響應的斷點。

// tailwind.config.js
module.exports = {
  theme: {
    screens: {
      'sm': '640px',
      'md': '768px',
      'lg': '1024px',
      'xl': '1280px',
      '2xl': '1536px',
    }
  }
}

想知道更多，可以看看自訂斷點的相關文件.

色彩

colors 這個 key 能讓你在專案中自訂共用的色板 (色票)。

// tailwind.config.js
module.exports = {
  theme: {
    colors: {
      transparent: 'transparent',
      black: '#000',
      white: '#fff',
      gray: {
        100: '#f7fafc',
        // ...
        900: '#1a202c',
      },

      // ...
    }
  }
}

一般來說，這些色彩會由像是 backgroundColor、borderColor、textColor 等之類所有與顏色相關的核心功能繼承

想知道更多，就看看自訂色彩相關文件.

間距

spacing 這個 key 能讓你在專案中自訂共用的間距以及尺寸級距。

// tailwind.config.js
module.exports = {
  theme: {
    spacing: {
      px: '1px',
      0: '0',
      0.5: '0.125rem',
      1: '0.25rem',
      1.5: '0.375rem',
      2: '0.5rem',
      2.5: '0.625rem',
      3: '0.75rem',
      3.5: '0.875rem',
      4: '1rem',
      5: '1.25rem',
      6: '1.5rem',
      7: '1.75rem',
      8: '2rem',
      9: '2.25rem',
      10: '2.5rem',
      11: '2.75rem',
      12: '3rem',
      14: '3.5rem',
      16: '4rem',
      20: '5rem',
      24: '6rem',
      28: '7rem',
      32: '8rem',
      36: '9rem',
      40: '10rem',
      44: '11rem',
      48: '12rem',
      52: '13rem',
      56: '14rem',
      60: '15rem',
      64: '16rem',
      72: '18rem',
      80: '20rem',
      96: '24rem',
    },
  }
}

一般來說，這些色彩會由 padding、margin、width、height、maxHeight、gap、inset、space 以及 translate 這些核心功能繼承。

想知道更多，可以閱讀自訂間距相關文件.

核心功能

theme 的其餘部份是用來個別配置每個核心功能可用的值。

舉例，像是 borderRadius 這個 key 可以讓你自訂要生成那些圓角功能：

module.exports = {
  theme: {
    borderRadius: {
      'none': '0',
      'sm': '.125rem',
      DEFAULT: '.25rem',
      'lg': '.5rem',
      'full': '9999px',
    },
  }
}

而 borderRadius 下的這些 key 決定了 borderRadius 功能的後綴詞，value 部份則是實際上 CSS 樣式所代表的值。

上面示範的 borderRadius 在配置後產生的就是下面這些 CSS class：

.rounded-none { border-radius: 0 }
.rounded-sm   { border-radius: .125rem }
.rounded      { border-radius: .25rem }
.rounded-lg   { border-radius: .5rem }
.rounded-full { border-radius: 9999px }

你會注意到使用 DEFAULT 這個 key 時所產生的 class rounded 並不帶有後綴詞，而這在 Tailwind 之中是很常見的慣例用法，且所有核心功能都適用。

如果想知道關於如何自訂特定的核心功能，可以直接閱讀該功能的文件。

有關所有可用主題參數及他們預設數值的完整規範，可以看看預設主題配置.

自訂預設主題

你的專案會自動繼承預設主題配置讓你可以開箱即用。如果你想要自訂預設主題的內容，根據你的目標，你有幾個不同的選擇。

在預設主題上擴充

如果你想要保存某個主題選項的預設值但同時也想增加新的數值，只需要在 theme 段落中把你想要擴充的數值加到 extend 這個 key 底下即可。

For example, if you wanted to add an extra breakpoint but preserve the existing ones, you could extend the screens property:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      // Adds a new breakpoint in addition to the default breakpoints
      screens: {
        '3xl': '1600px',
      }
    }
  }
}

覆寫預設主題

To override an option in the default theme, add your overrides directly under the theme section of your tailwind.config.js:

// tailwind.config.js
module.exports = {
  theme: {
    // Replaces all of the default `opacity` values
    opacity: {
      '0': '0',
      '20': '0.2',
      '40': '0.4',
      '60': '0.6',
      '80': '0.8',
      '100': '1',
    }
  }
}

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.

You can of course both override some parts of the default theme and extend other parts of the default theme within the same configuration:

// tailwind.config.js
module.exports = {
  theme: {
    opacity: {
      '0': '0',
      '20': '0.2',
      '40': '0.4',
      '60': '0.6',
      '80': '0.8',
      '100': '1',
    },
    extend: {
      screens: {
        '3xl': '1600px',
      }
    }
  }
}

Referencing other values

If you need to reference another value in your theme, you can do so by providing a closure instead of a static value. The closure will receive a theme() function that you can use to look up other values in your theme using dot notation.

For example, you could generate fill utilities for every color in your color palette by referencing theme('colors') in your fill configuration:

// tailwind.config.js
module.exports = {
  theme: {
    colors: {
      // ...
    },
    fill: theme => theme('colors')
  }
}

The theme() function attempts to find the value you are looking for from the fully merged theme object, so it can reference your own customizations as well as the default theme values. It also works recursively, so as long as there is a static value at the end of the chain it will be able to resolve the value you are looking for.

Note that you can only use this kind of closure with top-level theme keys, not the keys inside of each section.

// tailwind.config.js
module.exports = {
  theme: {
    fill: theme => ({
      gray: theme('colors.gray')
    })
  }
}

Referencing the default theme

If you’d like to reference a value in the default theme for any reason, you can import it from tailwindcss/defaultTheme.

One example of where this is useful is if you’d like to add a font family to one of Tailwind’s default font stacks:

// tailwind.config.js
const defaultTheme = require('tailwindcss/defaultTheme')

module.exports = {
  theme: {
    extend: {
      fontFamily: {
        sans: [
          'Lato',
          ...defaultTheme.fontFamily.sans,
        ]
      }
    }
  }
}

Disabling an entire core plugin

If you don’t want to generate any classes for a certain core plugin, it’s better to set that plugin to false in your corePlugins configuration than to provide an empty object for that key in your theme configuration.

// tailwind.config.js
module.exports = {
  corePlugins: {
    opacity: false,
  }
}

The end result is the same, but since many core plugins expose no configuration they can only be disabled using corePlugins anyways, so it’s better to be consistent.

Adding your own keys

There are a number of situations where it can be useful to add your own keys to the theme object.

One example of this is adding new keys to create a single source of truth for values that are common between multiple core plugins. For example, you could extract a shared positions object that could be referenced by both the backgroundPosition and objectPosition plugins:

// tailwind.config.js
module.exports = {
  theme: {
    positions: {
      bottom: 'bottom',
      center: 'center',
      left: 'left',
      'left-bottom': 'left bottom',
      'left-top': 'left top',
      right: 'right',
      'right-bottom': 'right bottom',
      'right-top': 'right top',
      top: 'top',
    },
    backgroundPosition: theme => theme('positions'),
    objectPosition: theme => theme('positions'),
  }
}

Another example is adding a new key to reference inside a custom plugin. For example, if you’ve written a filters plugin for your project, you might add a filters key to your theme object that the plugin references:

// tailwind.config.js
module.exports = {
  theme: {
    filters: {
      none: 'none',
      grayscale: 'grayscale(1)',
      invert: 'invert(1)',
      sepia: 'sepia(1)',
    }
  },
  plugins: [
    require('./plugins/filters')
  ],
}

Since the entire theme object is available in your CSS using the theme function, you might also add a key just to be able to reference it in your CSS.

Configuration reference

Except for screens, colors, and spacing, all of the keys in the theme object map to one of Tailwind’s core plugins. Since many plugins are responsible for CSS properties that only accept a static set of values (like float for example), note that not every plugin has a corresponding key in the theme object.

All of these keys are also available under the theme.extend key to enable extending the default theme.