Tailwind CSS v4 Gradient Utilities

Tailwind CSS v4 Gradient Utilities: bg-linear, bg-radial, bg-conic

With Tailwind CSS v4, the gradient utility API underwent a significant restructuring that replaces the v3 bg-gradient-to-* pattern with a more explicit naming scheme. The bg-gradient-to-* classes are gone. In their place, bg-linear-to-r, bg-radial, and bg-conic define the gradient type and direction as a single utility¹. Color stops attach with from-*, via-*, and to-* modifiers that accept any color token. The /oklch modifier on the type class enables OKLCH interpolation without writing any custom CSS².

Arbitrary values handle angles and colors outside the preset palette: bg-[linear-gradient(135deg,_#e66465,_#9198e5)] works as expected, with underscores replacing spaces inside brackets². This guide covers the utility syntax, the v3-to-v4 migration, and arbitrary value patterns. For React-specific usage including dynamic stop colors and JSX patterns, see the React and Tailwind stack guide linked in the Framework Guides section below.

Gradient type and direction utilities

Three base utilities define the gradient type: bg-linear, bg-radial, and bg-conic³. Direction modifiers attach to bg-linear: bg-linear-to-r, bg-linear-to-br, bg-linear-to-b, bg-linear-to-tl, and five other compass directions. bg-radial and bg-conic have no direction modifiers in the core utilities since radial gradients expand from a center point and conic gradients rotate around one.

The /oklch modifier appends to the type class before the direction: bg-linear-to-r/oklch routes the interpolation through the OKLCH perceptual color space. Combining it with from-blue-500 to-orange-400 produces a vivid midpoint instead of the grey midpoint that sRGB interpolation produces. Yet /oklch requires Tailwind v4 and does not back-port to v3. Consequently, any stylesheet using /oklch implicitly requires the v4 build pipeline.

Direction modifier reference

Eight direction modifiers attach to bg-linear: -to-r, -to-l, -to-t, -to-b, -to-tr, -to-tl, -to-br, and -to-bl. Each corresponds to a 45-degree compass direction, so bg-linear-to-br produces a diagonal gradient pointing toward the bottom-right corner of the element. These modifiers only apply to bg-linear; bg-radial and bg-conic have no direction variants because they expand from or rotate around a center point. For angles between the compass points, such as 220 degrees or 315 degrees, arbitrary value syntax handles the precise angle without requiring a custom utility. The nine compass directions cover the most common gradient angles in UI design, and the arbitrary value syntax fills in the remaining cases without bloating the utility API.

Because the preset set covers the common 45-degree steps, most interface gradients never need an arbitrary value. The Tailwind v4 build only emits the gradient classes your markup actually references, so adding a few diagonal directions does not bloat the output CSS. To build an angle the compass classes don't cover, paste a plain CSS gradient value into an arbitrary value bracket, which needs no custom utility and no config change.

Stop modifiers: from-*, via-*, and to-*

Color stops attach to any gradient type class using from-*, via-*, and to-* modifiers³. from-violet-500 sets the start color, to-pink-500 sets the end, and via-purple-400 inserts a midpoint stop. Multiple via-* modifiers are valid and stack in order. All three modifiers accept any Tailwind color token, opacity modifiers (from-violet-500/80), and arbitrary values (from-[#e66465]). For teams migrating large codebases incrementally, running a regex search for the bg-gradient-to- pattern catches every instance including those in dynamically constructed class strings that a simple text search might miss.

v3 to v4 migration

The v3 from-*, via-*, and to-* classes remain in v4 and work identically. The breaking change is the type and direction class: replace bg-gradient-to-r with bg-linear-to-r, bg-gradient-to-br with bg-linear-to-br, and so on¹. Running a text search for bg-gradient-to in the codebase identifies all instances needing update. Furthermore, the bg-none utility still exists in v4 for removing a background image; use it to clear a gradient in an override context. For teams migrating large codebases incrementally, running a regex search for the bg-gradient-to- pattern catches every instance including those in dynamically constructed class strings that a simple text search might miss. After replacing all instances, running the Tailwind v4 build and searching the compiled CSS for the v3 gradient-to pattern confirms that every old class has been successfully updated, giving you confidence that no stale references remain in the output bundle.

Arbitrary values for custom angles and non-palette colors

Arbitrary value syntax covers gradients not expressible as preset classes. bg-[linear-gradient(135deg,_#e66465,_#9198e5)] applies a 135-degree linear gradient with two hex stops. Underscores inside brackets convert to spaces in the CSS output; multi-word arbitrary values use underscores where the CSS value would have a space. The CapyToolkit gradient builder outputs CSS gradient values that paste directly into the brackets of any Tailwind arbitrary value class, so you can design the gradient visually and then drop the result into your markup without manual syntax conversion.

Combining arbitrary values with color tokens

Mixing arbitrary and token values in one gradient uses a Tailwind CSS variable reference alongside a literal hex inside the bracket. Tailwind v4 exposes all color tokens as CSS custom properties using the color name and shade as the property name, making them accessible inside arbitrary values through the var() function⁴. Consequently, arbitrary gradient values can reference the design system palette without duplicating hex codes. The CapyToolkit gradient builder outputs CSS gradient values that paste directly into the brackets of any Tailwind arbitrary value class, so arbitrary gradients can reference the design system palette through a variable reference instead of duplicating hex codes. This approach keeps your gradient definitions DRY: when the design team updates a brand color in the Tailwind config, every arbitrary gradient that references that token updates automatically on the next build without any manual find-and-replace across template files.

Gradient text with bg-clip-text in Tailwind v4

Gradient text applies the gradient to the fill of text letterforms rather than the element background. In Tailwind v4, the class combination is: bg-linear-to-r from-violet-500 to-pink-500 bg-clip-text text-transparent applied to a heading or inline element⁵. bg-clip-text restricts the gradient background to the area occupied by text glyphs. text-transparent makes the text fill transparent, revealing the gradient through the letterforms instead of showing the default text color.

The pattern requires all three classes to produce the intended result. Applying the gradient classes without bg-clip-text covers the entire element background. Adding bg-clip-text without text-transparent hides the gradient behind opaque text fill. Only when all three are present does the gradient fill show through the letterforms. Responsive modifiers work on gradient text classes identically to other Tailwind utilities, and the dark: modifier independently controls stop colors for dark mode without duplicating the full class set.

Migrating from Tailwind v3 requires replacing every bg-gradient-to-* class in your codebase. Each maps directly to a v4 class: bg-gradient-to-r becomes bg-linear-to-r, bg-gradient-to-br becomes bg-linear-to-br. Running a text search for bg-gradient-to identifies every class needing an update. After replacing all instances, run the Tailwind v4 build and search the compiled CSS for the v3 gradient-to pattern; if nothing appears, all v3 classes have been successfully replaced.

When to use this

Use Tailwind gradient utilities for static gradient classes in HTML and template files. Switch to arbitrary values or CSS custom properties when gradients involve runtime-dynamic stop colors, complex multi-stop patterns, or angle values outside the preset compass directions.

Examples