Add support for defining simple custom utilities in CSS via @utility (#14044)

This PR allows you to add custom utilities to your project via the new
`@utility` rule.

For example, given the following:
```css
@Utility text-trim {
  text-box-trim: both;
  text-box-edge: cap alphabetic;
}
```

A new `text-trim` utility is available and can be used directly or with
variants:
```html
<div class="text-trim">...</div>
<div class="hover:text-trim">...</div>
<div class="lg:dark:text-trim">...</div>
```

If a utility is defined more than one time the latest definition will be
used:
```css
@Utility text-trim {
  text-box-trim: both;
  text-box-edge: cap alphabetic;
}

@Utility text-trim {
  text-box-trim: both;
  text-box-edge: cap ideographic;
}
```

Then using `text-trim` will produce the following CSS:
```css
.text-trim {
  text-box-trim: both;
  text-box-edge: cap ideographic;
}
```

You may also override specific existing utilities with this — for
example to add a `text-rendering` property to the `text-sm` utility:
```css
@Utility text-sm {
  font-size: var(--font-size-sm, 0.875rem);
  line-height: var(--font-size-sm--line-height, 1.25rem);
  text-rendering: optimizeLegibility;
}
```

Though it's preferred, should you not need to add properties, to
override the theme instead.

Lastly, utilities with special characters do not need to be escaped like
you would for a class name in a selector:
```css
@Utility push-1/2 {
  right: 50%;
}
```

We do however explicitly error on certain patterns that we want to
reserve for future use, for example `push-*` and `push-[15px]`.

---------

Co-authored-by: Adam Wathan <[email protected]>
Co-authored-by: Adam Wathan <[email protected]>

Author: thecrypticace

CHANGELOG.md

@@ -22,6 +22,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Add support for basic `addVariant` plugins with new `@plugin` directive ([#13982](https://github.com/tailwindlabs/tailwindcss/pull/13982), [#14008](https://github.com/tailwindlabs/tailwindcss/pull/14008))
 - Add `@variant` at-rule for defining custom variants in CSS ([#13992](https://github.com/tailwindlabs/tailwindcss/pull/13992), [#14008](https://github.com/tailwindlabs/tailwindcss/pull/14008))
+- Add `@utility` at-rule for defining custom utilities in CSS ([#14044](https://github.com/tailwindlabs/tailwindcss/pull/14044))
 
 ## [4.0.0-alpha.17] - 2024-07-04
 

packages/tailwindcss/src/candidate.ts

@@ -249,6 +249,25 @@ export function parseCandidate(input: string, designSystem: DesignSystem): Candi
     base = base.slice(1)
   }
 
+  // Candidates that start with a dash are the negative versions of another
+  // candidate, e.g. `-mx-4`.
+  if (base[0] === '-') {
+    negative = true
+    base = base.slice(1)
+  }
+
+  // Check for an exact match of a static utility first as long as it does not
+  // look like an arbitrary value.
+  if (designSystem.utilities.has(base, 'static') && !base.includes('[')) {
+    return {
+      kind: 'static',
+      root: base,
+      variants: parsedCandidateVariants,
+      negative,
+      important,
+    }
+  }
+
   // Figure out the new base and the modifier segment if present.
   //
   // E.g.:
@@ -307,13 +326,6 @@ export function parseCandidate(input: string, designSystem: DesignSystem): Candi
     }
   }
 
-  // Candidates that start with a dash are the negative versions of another
-  // candidate, e.g. `-mx-4`.
-  if (baseWithoutModifier[0] === '-') {
-    negative = true
-    baseWithoutModifier = baseWithoutModifier.slice(1)
-  }
-
   // The root of the utility, e.g.: `bg-red-500`
   //                                 ^^
   let root: string | null = null
@@ -345,28 +357,16 @@ export function parseCandidate(input: string, designSystem: DesignSystem): Candi
 
     // The root of the utility should exist as-is in the utilities map. If not,
     // it's an invalid utility and we can skip continue parsing.
-    if (!designSystem.utilities.has(root)) return null
+    if (!designSystem.utilities.has(root, 'functional')) return null
 
     value = baseWithoutModifier.slice(idx + 1)
   }
 
   // Not an arbitrary value
   else {
-    ;[root, value] = findRoot(baseWithoutModifier, designSystem.utilities)
-  }
-
-  // If the root is null, but it contains a `/`, then it could be that we are
-  // dealing with a functional utility that contains a modifier but doesn't
-  // contain a value.
-  //
-  // E.g.: `@container/parent`
-  if (root === null && base.includes('/')) {
-    let [rootWithoutModifier, rootModifierSegment = null] = segment(base, '/')
-
-    modifierSegment = rootModifierSegment
-
-    // Try to find the root and value, without the modifier present
-    ;[root, value] = findRoot(rootWithoutModifier, designSystem.utilities)
+    ;[root, value] = findRoot(baseWithoutModifier, (root: string) => {
+      return designSystem.utilities.has(root, 'functional')
+    })
   }
 
   // If there's no root, the candidate isn't a valid class and can be discarded.
@@ -377,24 +377,6 @@ export function parseCandidate(input: string, designSystem: DesignSystem): Candi
   // can skip any further parsing.
   if (value === '') return null
 
-  let kind = designSystem.utilities.kind(root)
-
-  if (kind === 'static') {
-    // Static utilities do not have a value
-    if (value !== null) return null
-
-    // Static utilities do not have a modifier
-    if (modifierSegment !== null) return null
-
-    return {
-      kind: 'static',
-      root,
-      variants: parsedCandidateVariants,
-      negative,
-      important,
-    }
-  }
-
   let candidate: Candidate = {
     kind: 'functional',
     root,
@@ -560,7 +542,9 @@ export function parseVariant(variant: string, designSystem: DesignSystem): Varia
     // - `group-hover/foo/bar`
     if (additionalModifier) return null
 
-    let [root, value] = findRoot(variantWithoutModifier, designSystem.variants)
+    let [root, value] = findRoot(variantWithoutModifier, (root) => {
+      return designSystem.variants.has(root)
+    })
 
     // Variant is invalid, therefore the candidate is invalid and we can skip
     // continue parsing it.
@@ -629,26 +613,25 @@ export function parseVariant(variant: string, designSystem: DesignSystem): Varia
 
 function findRoot(
   input: string,
-  lookup: { has: (input: string) => boolean },
+  exists: (input: string) => boolean,
 ): [string | null, string | null] {
-  // If the lookup has an exact match, then that's the root.
-  if (lookup.has(input)) return [input, null]
+  // If there is an exact match, then that's the root.
+  if (exists(input)) return [input, null]
 
   // Otherwise test every permutation of the input by iteratively removing
   // everything after the last dash.
   let idx = input.lastIndexOf('-')
   if (idx === -1) {
     // Variants starting with `@` are special because they don't need a `-`
     // after the `@` (E.g.: `@-lg` should be written as `@lg`).
-    if (input[0] === '@' && lookup.has('@')) {
+    if (input[0] === '@' && exists('@')) {
       return ['@', input.slice(1)]
     }
 
     return [null, null]
   }
 
-  // Determine the root and value by testing permutations of the incoming input
-  // against the lookup table.
+  // Determine the root and value by testing permutations of the incoming input.
   //
   // In case of a candidate like `bg-red-500`, this looks like:
   //
@@ -658,7 +641,7 @@ function findRoot(
   do {
     let maybeRoot = input.slice(0, idx)
 
-    if (lookup.has(maybeRoot)) {
+    if (exists(maybeRoot)) {
       return [maybeRoot, input.slice(idx + 1)]
     }
 

packages/tailwindcss/src/compile.ts

@@ -117,14 +117,20 @@ export function compileAstNodes(rawCandidate: string, designSystem: DesignSystem
 
   // Handle named utilities
   else if (candidate.kind === 'static' || candidate.kind === 'functional') {
-    // Safety: At this point it is safe to use TypeScript's non-null assertion
-    // operator because if the `candidate.root` didn't exist, `parseCandidate`
-    // would have returned `null` and we would have returned early resulting
-    // in not hitting this code path.
-    let { compileFn } = designSystem.utilities.get(candidate.root)!
+    let fns = designSystem.utilities.get(candidate.root)
 
     // Build the node
-    let compiledNodes = compileFn(candidate)
+    let compiledNodes: AstNode[] | undefined
+
+    for (let i = fns.length - 1; i >= 0; i--) {
+      let fn = fns[i]
+
+      if (candidate.kind !== fn.kind) continue
+
+      compiledNodes = fn.compileFn(candidate)
+      if (compiledNodes) break
+    }
+
     if (compiledNodes === undefined) return null
 
     nodes = compiledNodes

packages/tailwindcss/src/index.ts

@@ -17,9 +17,12 @@ import { buildDesignSystem, type DesignSystem } from './design-system'
 import { Theme } from './theme'
 import { segment } from './utils/segment'
 
+const IS_VALID_UTILITY_NAME = /^[a-z][a-zA-Z0-9/%._-]*$/
+
 type PluginAPI = {
   addVariant(name: string, variant: string | string[] | CssInJs): void
 }
+
 type Plugin = (api: PluginAPI) => void
 
 type CompileOptions = {
@@ -52,6 +55,7 @@ export function compile(
   let theme = new Theme()
   let plugins: Plugin[] = []
   let customVariants: ((designSystem: DesignSystem) => void)[] = []
+  let customUtilities: ((designSystem: DesignSystem) => void)[] = []
   let firstThemeRule: Rule | null = null
   let keyframesRules: Rule[] = []
 
@@ -65,6 +69,33 @@ export function compile(
       return
     }
 
+    // Collect custom `@utility` at-rules
+    if (node.selector.startsWith('@utility ')) {
+      let name = node.selector.slice(9).trim()
+
+      if (!IS_VALID_UTILITY_NAME.test(name)) {
+        throw new Error(
+          `\`@utility ${name}\` defines an invalid utility name. Utilities should be alphanumeric and start with a lowercase letter.`,
+        )
+      }
+
+      if (node.nodes.length === 0) {
+        throw new Error(
+          `\`@utility ${name}\` is empty. Utilities should include at least one property.`,
+        )
+      }
+
+      customUtilities.push((designSystem) => {
+        designSystem.utilities.static(name, (candidate) => {
+          if (candidate.negative) return
+          return structuredClone(node.nodes)
+        })
+      })
+
+      replaceWith([])
+      return
+    }
+
     // Register custom variants from `@variant` at-rules
     if (node.selector.startsWith('@variant ')) {
       if (parent !== null) {
@@ -224,6 +255,10 @@ export function compile(
     customVariant(designSystem)
   }
 
+  for (let customUtility of customUtilities) {
+    customUtility(designSystem)
+  }
+
   let api: PluginAPI = {
     addVariant(name, variant) {
       // Single selector

packages/tailwindcss/src/intellisense.ts

@@ -11,18 +11,13 @@ export type ClassEntry = [string, ClassMetadata]
 export function getClassList(design: DesignSystem): ClassEntry[] {
   let list: [string, ClassMetadata][] = []
 
-  for (let [utility, fn] of design.utilities.entries()) {
-    if (typeof utility !== 'string') {
-      continue
-    }
-
-    // Static utilities only work as-is
-    if (fn.kind === 'static') {
-      list.push([utility, { modifiers: [] }])
-      continue
-    }
+  // Static utilities only work as-is
+  for (let utility of design.utilities.keys('static')) {
+    list.push([utility, { modifiers: [] }])
+  }
 
-    // Functional utilities have their own list of completions
+  // Functional utilities have their own list of completions
+  for (let utility of design.utilities.keys('functional')) {
     let completions = design.utilities.getCompletions(utility)
 
     for (let group of completions) {