Add bg-{top,bottom}-{left,right} utilities (#17378)

We’re using this naming for `mask-*` and `mask-radial-at-*` position
utilities and we want to be consistent. The old ones for
`background-position` will stay but are deprecated

---------

Co-authored-by: Robin Malfait <[email protected]>

Author: thecrypticace

CHANGELOG.md

@@ -20,11 +20,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - _Experimental_: Add `wrap-anywhere`, `wrap-break-word`, and `wrap-normal` utilities ([#12128](https://github.com/tailwindlabs/tailwindcss/pull/12128))
 - _Experimental_: Add `@source inline(…)` ([#17147](https://github.com/tailwindlabs/tailwindcss/pull/17147))
 - _Experimental_: Add `@source not` ([#17255](https://github.com/tailwindlabs/tailwindcss/pull/17255))
+- Added new `bg-{top,bottom}-{left,right}` utilities ([#17378](https://github.com/tailwindlabs/tailwindcss/pull/17378))
 
 ### Fixed
 
 - Fix symlink issues when resolving `@source` directives ([#17391](https://github.com/tailwindlabs/tailwindcss/pull/17391))
 
+### Changed
+
+- Deprecated `bg-{left,right}-{top,bottom}` utilities ([#17378](https://github.com/tailwindlabs/tailwindcss/pull/17378))
+
 ## [4.0.17] - 2025-03-26
 
 ### Fixed

packages/tailwindcss/src/__snapshots__/intellisense.test.ts.snap

@@ -2156,6 +2156,8 @@ exports[`getClassList 1`] = `
   "bg-blend-screen",
   "bg-blend-soft-light",
   "bg-bottom",
+  "bg-bottom-left",
+  "bg-bottom-right",
   "bg-center",
   "bg-clip-border",
   "bg-clip-content",
@@ -2326,8 +2328,6 @@ exports[`getClassList 1`] = `
   "bg-inherit/95",
   "bg-inherit/100",
   "bg-left",
-  "bg-left-bottom",
-  "bg-left-top",
   "bg-linear-0",
   "bg-linear-0/oklab",
   "bg-linear-0/oklch",
@@ -2529,10 +2529,10 @@ exports[`getClassList 1`] = `
   "bg-repeat-x",
   "bg-repeat-y",
   "bg-right",
-  "bg-right-bottom",
-  "bg-right-top",
   "bg-scroll",
   "bg-top",
+  "bg-top-left",
+  "bg-top-right",
   "bg-transparent",
   "bg-transparent/0",
   "bg-transparent/5",

packages/tailwindcss/src/compat/legacy-utilities.ts

@@ -19,6 +19,16 @@ export function registerLegacyUtilities(designSystem: DesignSystem) {
     ])
   }
 
+  // Legacy `background-position` utilities for compatibility with v4.0 and earlier
+  designSystem.utilities.static('bg-left-top', () => [decl('background-position', 'left top')])
+  designSystem.utilities.static('bg-right-top', () => [decl('background-position', 'right top')])
+  designSystem.utilities.static('bg-left-bottom', () => [
+    decl('background-position', 'left bottom'),
+  ])
+  designSystem.utilities.static('bg-right-bottom', () => [
+    decl('background-position', 'right bottom'),
+  ])
+
   designSystem.utilities.functional('max-w-screen', (candidate) => {
     if (!candidate.value) return
     if (candidate.value.kind === 'arbitrary') return

packages/tailwindcss/src/utilities.test.ts

@@ -10190,20 +10190,26 @@ test('bg', async () => {
         'bg-scroll',
 
         // background-position
-        'bg-center',
         'bg-top',
-        'bg-right-top',
-        'bg-right-bottom',
+        'bg-top-left',
+        'bg-top-right',
         'bg-bottom',
-        'bg-left-bottom',
+        'bg-bottom-left',
+        'bg-bottom-right',
         'bg-left',
-        'bg-left-top',
+        'bg-right',
+        'bg-center',
         'bg-[50%]',
         'bg-[120px]',
         'bg-[120px_120px]',
         'bg-[length:120px_120px]',
         'bg-[position:120px_120px]',
         'bg-[size:120px_120px]',
+        // Legacy versions in v4.0 and earlier
+        'bg-right-top',
+        'bg-right-bottom',
+        'bg-left-bottom',
+        'bg-left-top',
 
         // background-repeat
         'bg-repeat',
@@ -10610,6 +10616,14 @@ test('bg', async () => {
       background-position: bottom;
     }
 
+    .bg-bottom-left {
+      background-position: 0 100%;
+    }
+
+    .bg-bottom-right {
+      background-position: 100% 100%;
+    }
+
     .bg-center {
       background-position: center;
     }
@@ -10626,6 +10640,10 @@ test('bg', async () => {
       background-position: 0 0;
     }
 
+    .bg-right {
+      background-position: 100%;
+    }
+
     .bg-right-bottom {
       background-position: 100% 100%;
     }
@@ -10638,6 +10656,14 @@ test('bg', async () => {
       background-position: top;
     }
 
+    .bg-top-left {
+      background-position: 0 0;
+    }
+
+    .bg-top-right {
+      background-position: 100% 0;
+    }
+
     .bg-no-repeat {
       background-repeat: no-repeat;
     }

packages/tailwindcss/src/utilities.ts

@@ -2390,15 +2390,15 @@ export function createUtilities(theme: Theme) {
   staticUtility('bg-local', [['background-attachment', 'local']])
   staticUtility('bg-scroll', [['background-attachment', 'scroll']])
 
-  staticUtility('bg-center', [['background-position', 'center']])
   staticUtility('bg-top', [['background-position', 'top']])
-  staticUtility('bg-right-top', [['background-position', 'right top']])
-  staticUtility('bg-right', [['background-position', 'right']])
-  staticUtility('bg-right-bottom', [['background-position', 'right bottom']])
+  staticUtility('bg-top-left', [['background-position', 'left top']])
+  staticUtility('bg-top-right', [['background-position', 'right top']])
   staticUtility('bg-bottom', [['background-position', 'bottom']])
-  staticUtility('bg-left-bottom', [['background-position', 'left bottom']])
+  staticUtility('bg-bottom-left', [['background-position', 'left bottom']])
+  staticUtility('bg-bottom-right', [['background-position', 'right bottom']])
   staticUtility('bg-left', [['background-position', 'left']])
-  staticUtility('bg-left-top', [['background-position', 'left top']])
+  staticUtility('bg-right', [['background-position', 'right']])
+  staticUtility('bg-center', [['background-position', 'center']])
 
   staticUtility('bg-repeat', [['background-repeat', 'repeat']])
   staticUtility('bg-no-repeat', [['background-repeat', 'no-repeat']])