theme() — tailwindcss Function Reference

Architecture documentation for the theme() function in css-functions.ts from the tailwindcss codebase.

Function typescript Oxide PreProcessors calls 4 called by 3

Entity Profile

Oxide→ PreProcessors→ theme() — tailwindcss Function Reference

Dependency Diagram

graph TD
  afa623bf_4f68_b25f_8bd7_1d00a4fcfe48["theme()"]
  1648a493_13b2_8170_f86b_607e088d9565["css-functions.ts"]
  afa623bf_4f68_b25f_8bd7_1d00a4fcfe48 -->|defined in| 1648a493_13b2_8170_f86b_607e088d9565
  3ee77e11_8d52_723b_aade_ff424151c955["legacyTheme()"]
  3ee77e11_8d52_723b_aade_ff424151c955 -->|calls| afa623bf_4f68_b25f_8bd7_1d00a4fcfe48
  e557c8a4_bb27_ee44_c462_9e238157ad04["buildDesignSystem()"]
  e557c8a4_bb27_ee44_c462_9e238157ad04 -->|calls| afa623bf_4f68_b25f_8bd7_1d00a4fcfe48
  f7f9b3da_5977_1aa6_3bcb_bfc607af4e8f["parseCss()"]
  f7f9b3da_5977_1aa6_3bcb_bfc607af4e8f -->|calls| afa623bf_4f68_b25f_8bd7_1d00a4fcfe48
  085cf56e_8188_afb1_04da_5ccd0fb7babc["rule()"]
  afa623bf_4f68_b25f_8bd7_1d00a4fcfe48 -->|calls| 085cf56e_8188_afb1_04da_5ccd0fb7babc
  49a8c506_c50e_ed4b_5a0e_0393edae2b6f["parse()"]
  afa623bf_4f68_b25f_8bd7_1d00a4fcfe48 -->|calls| 49a8c506_c50e_ed4b_5a0e_0393edae2b6f
  985244c4_0648_c5ac_af17_30241fffd9de["injectFallbackForInitialFallback()"]
  afa623bf_4f68_b25f_8bd7_1d00a4fcfe48 -->|calls| 985244c4_0648_c5ac_af17_30241fffd9de
  d6cf80a6_8130_7069_e60d_09156f156b67["toCss()"]
  afa623bf_4f68_b25f_8bd7_1d00a4fcfe48 -->|calls| d6cf80a6_8130_7069_e60d_09156f156b67
  style afa623bf_4f68_b25f_8bd7_1d00a4fcfe48 fill:#6366f1,stroke:#818cf8,color:#fff

Relationship Graph

Source Code

packages/tailwindcss/src/css-functions.ts lines 68–127

function theme(
  designSystem: DesignSystem,
  source: AstNode,
  path: string,
  ...fallback: string[]
): string {
  if (!path.startsWith('--')) {
    throw new Error(`The --theme(…) function can only be used with CSS variables from your theme.`)
  }

  let inline = false

  // Handle `--theme(… inline)` to force inline resolution
  if (path.endsWith(' inline')) {
    inline = true
    path = path.slice(0, -7)
  }

  // If the `--theme(…)` function is used within an at-rule (e.g. `@media (width >= --theme(…)))`,
  // we have to always inline the result since CSS does not support CSS variables in these positions
  if (source.kind === 'at-rule') {
    inline = true
  }

  let resolvedValue = designSystem.resolveThemeValue(path, inline)

  if (!resolvedValue) {
    if (fallback.length > 0) return fallback.join(', ')
    throw new Error(
      `Could not resolve value for theme function: \`theme(${path})\`. Consider checking if the variable name is correct or provide a fallback value to silence this error.`,
    )
  }

  if (fallback.length === 0) {
    return resolvedValue
  }

  let joinedFallback = fallback.join(', ')
  if (joinedFallback === 'initial') return resolvedValue

  // When the resolved value returns `initial`, resolve with the fallback value
  if (resolvedValue === 'initial') return joinedFallback

  // Inject the fallback of a `--theme(…)` function into the fallback of a referenced `--theme(…)`
  // function or `var(…)` declaration. If the referenced function already defines a fallback, we use
  // a potential fallback value of `initial` in the referenced function to determine if we should
  // inject the fallback value of the caller. If that's not the case, we keep the fallback as-is
  // (this is needed for theme variables in reference-mode).
  if (
    resolvedValue.startsWith('var(') ||
    resolvedValue.startsWith('theme(') ||
    resolvedValue.startsWith('--theme(')
  ) {
    let valueAst = ValueParser.parse(resolvedValue)
    injectFallbackForInitialFallback(valueAst, joinedFallback)
    return ValueParser.toCss(valueAst)
  }

  return resolvedValue
}