Tailwind Syntax Gradients

Tailwind CSS Gradients

v4 expanded the gradient API from v3's eight linear directions to a full three-family system (linear, radial, conic) with seven interpolation colour spaces, angle-based linear gradients, and percentage stop positions. v3 stays linear-only with the legacy bg-gradient-* prefix.

Companion skills :

• tailwind-syntax-utility-classes : the broader background utility surface
• tailwind-core-v3-vs-v4 : the v4-renamed utilities table (bg-gradient -> bg-linear)
• tailwind-impl-migration-v3-v4 : codemod that handles the rename

Quick Reference : v3 vs v4 Cheat Sheet

ALWAYS run npx @tailwindcss/upgrade on v3-to-v4 migration : it renames every bg-gradient-* to bg-linear-* automatically. NEVER hand-edit the rename across a large codebase ; the codemod is exhaustive.

Source : https://tailwindcss.com/blog/tailwindcss-v4 ("we've renamed bg-gradient-* to bg-linear-*").

Linear Gradients : v4 Direction Utilities

Identical eight directions exist in v3 with bg-gradient-to-* prefix.

Linear Gradients : Angle Utilities (v4-only)

<div class="bg-linear-45 from-indigo-500 to-pink-500"></div>
<div class="bg-linear-90 from-red-500 to-blue-500"></div>
<div class="-bg-linear-45 from-indigo-500 to-pink-500"></div>

Angle utilities REPLACE the v3 arbitrary-only pattern bg-[linear-gradient(45deg,#A,#B)]. NEVER use the arbitrary form in v4 for simple angle gradients ; the utility is shorter and uses the configured interpolation space.

Radial Gradients (v4)

<div class="bg-radial from-white to-zinc-900"></div>
<div class="bg-radial-[at_top_left] from-blue-500 to-transparent"></div>
<div class="bg-radial-[at_25%_25%] from-white to-zinc-900 to-75%"></div>

v3 has NO native radial utility. Use arbitrary bg-[radial-gradient(circle,#A,#B)] or stay on v3.

Source : https://tailwindcss.com/docs/background-image

Conic Gradients (v4)

<div class="bg-conic from-red-500 via-yellow-500 to-red-500"></div>
<div class="bg-conic-90 from-red-500 to-blue-500"></div>
<div class="bg-conic-180 from-red-500 to-blue-500"></div>
<div class="-bg-conic-45 from-red-500 to-blue-500"></div>

ALWAYS include from-{color} AND to-{color} (and typically via-{color}) on a bg-conic. NEVER use bg-conic with only one stop : the gradient collapses to a single colour and the conic effect is invisible.

For a smooth full-circle rainbow :

<div class="size-24 rounded-full
  bg-conic/[in_hsl_longer_hue] from-red-600 to-red-600"></div>

The longer-hue interpolation walks the entire colour wheel between two identical endpoints.

Color Stops : Colour Utilities

<div class="bg-linear-to-r from-indigo-500 via-purple-500 to-pink-500"></div>

ALWAYS pair from- with to-. NEVER ship a gradient with only from- ; the to- defaults to transparent, which means the gradient fades to nothing.

Color Stops : Position Utilities (v4)

<!-- from at 10%, via at 30%, to at 90% -->
<div class="bg-linear-to-r
  from-blue-500 from-10%
  via-purple-500 via-30%
  to-pink-500 to-90%"></div>

<!-- start the gradient OUTSIDE the box for a partial visible band -->
<div class="bg-linear-to-r
  -from-10% from-blue-500
  to-pink-500"></div>

v3 has NO native position utilities. Use arbitrary bg-[linear-gradient(to_right,#A_10%,#B)] or stay on v3.

Interpolation Modifiers (v4)

<div class="bg-linear-to-r/srgb   from-indigo-500 to-teal-400"></div>
<div class="bg-linear-to-r/oklab  from-indigo-500 to-teal-400"></div>   <!-- default -->
<div class="bg-linear-to-r/oklch  from-indigo-500 to-teal-400"></div>
<div class="bg-linear-to-r/hsl    from-indigo-500 to-teal-400"></div>
<div class="bg-linear-to-r/longer from-red-500    to-red-500"></div>
<div class="bg-linear-to-r/shorter from-red-500   to-blue-500"></div>
<div class="bg-linear-to-r/increasing from-red-500 to-blue-500"></div>
<div class="bg-linear-to-r/decreasing from-red-500 to-blue-500"></div>

Source : https://tailwindcss.com/blog/tailwindcss-v4 ("Using polar color spaces like OKLCH or HSL can lead to much more vivid gradients when the from-* and to-* colors are far apart on the color wheel. We're using OKLAB by default in v4.0").

NEVER use /srgb for a saturated red to saturated green gradient unless you actively want the gray midpoint. The default /oklab and the polar /oklch both keep the midpoint vivid.

Decision Tree : Which Interpolation?

Are the two colours close on the hue wheel (e.g. blue and purple)?
├── YES → default /oklab works
│         (no special modifier needed)
│
└── NO  → Far apart (red and green, blue and orange)?
    ├── Smooth perceptual blend → /oklch
    ├── Vivid hue rotation through wheel → /hsl
    ├── Full circle through every hue → /longer
    └── Want legacy CSS look (gray midpoint) → /srgb (explicit opt-in)

ALWAYS test /oklch against the default /oklab for complementary-colour gradients ; the difference is dramatic. NEVER ship a red-to-green gradient on /srgb by accident : you get a muddy gray middle.

Arbitrary Values

Every utility supports the [value] and (--var) escape hatches :

<!-- Full arbitrary linear gradient -->
<div class="bg-linear-[25deg,red_5%,yellow_60%,lime_90%,teal]"></div>

<!-- Conic with explicit from + center + colour stops -->
<div class="bg-conic-[from_45deg_at_50%_25%,red,blue,red]"></div>

<!-- Reading angle from CSS variable -->
<div class="bg-linear-(--my-angle) from-blue-500 to-purple-500"></div>

Underscores convert to spaces in arbitrary values : bg-linear-[to_right] emits linear-gradient(to right, ...).

v3 Pattern : Linear-Only With Arbitrary For Everything Else

<!-- v3 simple linear : utility available -->
<div class="bg-gradient-to-r from-blue-500 to-purple-500"></div>

<!-- v3 angle gradient : MUST be arbitrary -->
<div class="bg-[linear-gradient(45deg,theme(colors.blue.500),theme(colors.purple.500))]"></div>

<!-- v3 radial : MUST be arbitrary -->
<div class="bg-[radial-gradient(circle,theme(colors.white),theme(colors.zinc.900))]"></div>

<!-- v3 conic : MUST be arbitrary -->
<div class="bg-[conic-gradient(from_45deg,theme(colors.red.500),theme(colors.blue.500))]"></div>

<!-- v3 stop positions : arbitrary -->
<div class="bg-[linear-gradient(to_right,theme(colors.blue.500)_10%,theme(colors.pink.500)_90%)]"></div>

theme(colors.blue.500) resolves the configured Tailwind colour at build time in v3. v4 dropped this in favour of var(--color-blue-500).

Stacking With Variants

<!-- Hover changes gradient direction -->
<div class="bg-linear-to-r hover:bg-linear-to-br
  from-blue-500 to-purple-500"></div>

<!-- Dark-mode variant changes colours -->
<div class="bg-linear-to-r from-blue-200 to-purple-200
  dark:from-blue-700 dark:to-purple-700"></div>

<!-- Responsive changes interpolation -->
<div class="bg-linear-to-r/srgb md:bg-linear-to-r/oklch
  from-red-500 to-green-500"></div>

The gradient utility and its colour stops are independent variants ; each gets its own prefix when conditional.

Reference Files

• references/methods.md : every utility with CSS output, default values, interpolation modifier list, browser baseline
• references/examples.md : side-by-side v3 vs v4 for every gradient category, real layouts (hero, button, badge, glow, conic spinner)
• references/anti-patterns.md : the rename trap, muddy-middle, lonely from-, conic-without-from, v3 angle-not-supported confusion

Verified Sources

• https://tailwindcss.com/docs/background-image (v4 full API)
• https://v3.tailwindcss.com/docs/background-image (v3 baseline)
• https://tailwindcss.com/blog/tailwindcss-v4 (announcement, default oklab, rename, interpolation rationale)