From 3412a9623d4fa5025e0d9c4f13be40d2a54af607 Mon Sep 17 00:00:00 2001
From: Jordan Pittman <jordan@cryptica.me>
Date: Fri, 28 Mar 2025 12:40:57 -0400
Subject: [PATCH] Add `bg-{position,size}-*` utilities (#17432)

This PR adds `bg-{position,size}-*` utilities that support arbitrary
values. This exist as the new preferred version of something like this:

```
bg-[120px_120px]
```

Is it size or position (hint: it's the 2nd one).

To override it you'd have to provide a data type:
```
bg-[size:120px_120px]
```


Now you can be more explicit and have better intellisense by writing
these:
```
bg-position-[120px_120px]
bg-size-[120px_120px]
```
---
 CHANGELOG.md                               |  1 +
 packages/tailwindcss/src/utilities.test.ts | 78 ++++++++++++++++++++++
 packages/tailwindcss/src/utilities.ts      | 12 ++++
 3 files changed, 91 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 434ac59e9..1e4d05324 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - _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))
+- Added new `bg-{position,size}-*` utilities for arbitrary values ([#17432](https://github.com/tailwindlabs/tailwindcss/pull/17432))
 
 ### Fixed
 
diff --git a/packages/tailwindcss/src/utilities.test.ts b/packages/tailwindcss/src/utilities.test.ts
index 649174306..1404daca8 100644
--- a/packages/tailwindcss/src/utilities.test.ts
+++ b/packages/tailwindcss/src/utilities.test.ts
@@ -10809,6 +10809,84 @@ test('bg', async () => {
   `)
 })
 
+test('bg-position', async () => {
+  expect(
+    await compileCss(
+      css`
+        @theme {
+          --color-red-500: #ef4444;
+        }
+        @tailwind utilities;
+      `,
+      ['bg-position-[120px]', 'bg-position-[120px_120px]', 'bg-position-[var(--some-var)]'],
+    ),
+  ).toMatchInlineSnapshot(`
+    ".bg-position-\\[120px\\] {
+      background-position: 120px;
+    }
+
+    .bg-position-\\[120px_120px\\] {
+      background-position: 120px 120px;
+    }
+
+    .bg-position-\\[var\\(--some-var\\)\\] {
+      background-position: var(--some-var);
+    }"
+  `)
+  expect(
+    await run([
+      'bg-position',
+      'bg-position/foo',
+      '-bg-position',
+      '-bg-position/foo',
+
+      'bg-position-[120px_120px]/foo',
+
+      '-bg-position-[120px_120px]',
+      '-bg-position-[120px_120px]/foo',
+    ]),
+  ).toEqual('')
+})
+
+test('bg-size', async () => {
+  expect(
+    await compileCss(
+      css`
+        @theme {
+          --color-red-500: #ef4444;
+        }
+        @tailwind utilities;
+      `,
+      ['bg-size-[120px]', 'bg-size-[120px_120px]', 'bg-size-[var(--some-var)]'],
+    ),
+  ).toMatchInlineSnapshot(`
+    ".bg-size-\\[120px\\] {
+      background-size: 120px;
+    }
+
+    .bg-size-\\[120px_120px\\] {
+      background-size: 120px 120px;
+    }
+
+    .bg-size-\\[var\\(--some-var\\)\\] {
+      background-size: var(--some-var);
+    }"
+  `)
+  expect(
+    await run([
+      'bg-size',
+      'bg-size/foo',
+      '-bg-size',
+      '-bg-size/foo',
+
+      'bg-size-[120px_120px]/foo',
+
+      '-bg-size-[120px_120px]',
+      '-bg-size-[120px_120px]/foo',
+    ]),
+  ).toEqual('')
+})
+
 test('from', async () => {
   expect(
     await compileCss(
diff --git a/packages/tailwindcss/src/utilities.ts b/packages/tailwindcss/src/utilities.ts
index dfe572d03..2913db2c5 100644
--- a/packages/tailwindcss/src/utilities.ts
+++ b/packages/tailwindcss/src/utilities.ts
@@ -2385,6 +2385,12 @@ export function createUtilities(theme: Theme) {
   staticUtility('bg-auto', [['background-size', 'auto']])
   staticUtility('bg-cover', [['background-size', 'cover']])
   staticUtility('bg-contain', [['background-size', 'contain']])
+  functionalUtility('bg-size', {
+    handle(value) {
+      if (!value) return
+      return [decl('background-size', value)]
+    },
+  })
 
   staticUtility('bg-fixed', [['background-attachment', 'fixed']])
   staticUtility('bg-local', [['background-attachment', 'local']])
@@ -2399,6 +2405,12 @@ export function createUtilities(theme: Theme) {
   staticUtility('bg-left', [['background-position', 'left']])
   staticUtility('bg-right', [['background-position', 'right']])
   staticUtility('bg-center', [['background-position', 'center']])
+  functionalUtility('bg-position', {
+    handle(value) {
+      if (!value) return
+      return [decl('background-position', value)]
+    },
+  })
 
   staticUtility('bg-repeat', [['background-repeat', 'repeat']])
   staticUtility('bg-no-repeat', [['background-repeat', 'no-repeat']])