theme() — tailwindcss Function Reference

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

Function typescript CompilerEngine ModuleResolution calls 4 called by 3

Entity Profile

CompilerEngine→ ModuleResolution→ theme() — tailwindcss Function Reference

Dependency Diagram

graph TD
  552e707a_ccba_b2a6_5917_15f7a417896b["theme()"]
  dc89164d_c61b_66e1_83f4_7a616b6a7dcb["legacyTheme()"]
  dc89164d_c61b_66e1_83f4_7a616b6a7dcb -->|calls| 552e707a_ccba_b2a6_5917_15f7a417896b
  cebe77e1_f0f2_aeee_417e_2192f5790344["buildDesignSystem()"]
  cebe77e1_f0f2_aeee_417e_2192f5790344 -->|calls| 552e707a_ccba_b2a6_5917_15f7a417896b
  26086ff1_0d4f_fdb2_3fc4_d0c999f90a8c["parseCss()"]
  26086ff1_0d4f_fdb2_3fc4_d0c999f90a8c -->|calls| 552e707a_ccba_b2a6_5917_15f7a417896b
  08f33202_11d1_569a_e8df_de23eb987e2f["rule()"]
  552e707a_ccba_b2a6_5917_15f7a417896b -->|calls| 08f33202_11d1_569a_e8df_de23eb987e2f
  0638028e_f2f7_8e77_2f19_1bd2ce4b2d6a["parse()"]
  552e707a_ccba_b2a6_5917_15f7a417896b -->|calls| 0638028e_f2f7_8e77_2f19_1bd2ce4b2d6a
  c85d11ae_ab39_c633_47f6_6b20e6acd2dc["injectFallbackForInitialFallback()"]
  552e707a_ccba_b2a6_5917_15f7a417896b -->|calls| c85d11ae_ab39_c633_47f6_6b20e6acd2dc
  f66dddcc_be1c_d082_4eb0_ec82ce3bf380["toCss()"]
  552e707a_ccba_b2a6_5917_15f7a417896b -->|calls| f66dddcc_be1c_d082_4eb0_ec82ce3bf380
  style 552e707a_ccba_b2a6_5917_15f7a417896b 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
}