Tailwind CSS v4 Gradient Utilities

Build linear, radial, and conic CSS gradients with a visual editor. Drag color stops, pick presets, and copy ready-to-use CSS, Tailwind, or custom property output.

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 utility1. 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 CSS2.

Arbitrary values handle angles and colors outside the preset palette: bg-[linear-gradient(135deg,_#e66465,_#9198e5)] works as expected, with underscores replacing spaces inside brackets2. 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.

What this page covers

  • bg-linear-to-r replaces the v3 bg-gradient-to-r class
  • /oklch modifier appended to the gradient type class to route interpolation through OKLCH

Opens the CSS Gradient Builder with this page's checklist shown at the top of the tool.

Open in the tool →

Gradient type and direction utilities

Three base utilities define the gradient type: bg-linear, bg-radial, and bg-conic3. 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-* modifiers3. 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 on1. 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() function4. 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 element5. 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

Hero section background with OKLCH interpolation

Apply bg-linear-to-br/oklch from-blue-600 to-purple-500 to the hero wrapper div. The /oklch modifier prevents the grey midpoint that sRGB produces between cool hues. Requires Tailwind v4.

Dark-mode responsive gradient that changes direction at a breakpoint

Combine responsive and dark modifiers: bg-linear-to-b md:bg-linear-to-r from-slate-800 to-slate-900. The gradient flows top-to-bottom on mobile and left-to-right on wider screens. dark: modifiers can swap the stop colors independently for light and dark themes.

Custom angle gradient with arbitrary value and palette colors

Use bg-[linear-gradient(135deg,_var(--color-violet-600),_var(--color-pink-500))] to set a precise diagonal angle while referencing the Tailwind palette tokens. Underscores in the bracket replace spaces in the CSS value.

Sources
  1. 1.

    Tailwind CSS, "Upgrade guide," tailwindcss.com, accessed June 2026. https://tailwindcss.com/docs/upgrade-guide

  2. 2.

    Tailwind CSS, "Tailwind CSS v4.0," tailwindcss.com, January 2025. https://tailwindcss.com/blog/tailwindcss-v4

  3. 3.

    Steven Richardson, "Tailwind bg-linear-to: v4 Gradient Utilities Explained," richdynamix.com, May 2026. https://richdynamix.com/articles/tailwind-v4-gradient-utilities-bg-linear-radial-conic

  4. 4.

    MDN Web Docs, "Using CSS custom properties (variables)," developer.mozilla.org, accessed June 2026. https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascading_variables/Using_custom_properties

  5. 5.

    MDN Web Docs, "background-clip CSS property," developer.mozilla.org, accessed June 2026. https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/background-clip

FAQ

bg-linear-to-r replaces bg-gradient-to-r. The full set of direction suffixes follows the same pattern: -to-r, -to-l, -to-t, -to-b, -to-tr, -to-tl, -to-br, -to-bl. The from-*, via-*, and to-* stop modifiers remain unchanged. CapyToolkit generates plain CSS gradient values rather than framework-specific class strings, so the output pastes directly into arbitrary value brackets for any of the v4 gradient utilities. Run a search for bg-gradient-to in your codebase to find all instances that need updating.

Append /oklch to the gradient type class: bg-linear-to-r/oklch. This adds in oklch to the CSS gradient function, routing the blend through the OKLCH perceptual color space. The result is a vivid midpoint between complementary hues instead of the grey midpoint sRGB produces.

Use an arbitrary value: bg-[linear-gradient(135deg,_#e66465,_#9198e5)]. Replace spaces in the CSS value with underscores inside the bracket. Reference Tailwind palette tokens as CSS variables, using the color name and shade as the custom property name inside the bracket value.

Yes, the stop modifiers are unchanged between v3 and v4. The breaking change is the type class: replace bg-gradient-to-* with bg-linear-to-* in v4. The stop modifier syntax and all color token names remain compatible.

Use bg-radial followed by from-* and to-* stop classes: bg-radial from-pink-400 to-purple-700. The gradient expands from the element center by default. For an off-center radial or a specific shape and size, use an arbitrary value: bg-[radial-gradient(circle_at_25%_75%,_#e66465,_transparent)].

Additional resources

Guides

CSS Gradient Text with background-clip Apply a CSS gradient to text using background-image and background-clip: text. Browser support, fallback strategy, and live examples with the gradient builder. Animating CSS Gradients with @property Animate CSS gradient stops smoothly using @property custom properties. Browser support, fallback patterns, and OKLCH hue-rotation animations. CSS Mesh Gradient Technique Build mesh-style gradients in CSS using multiple layered radial-gradient() values on the same background-image. No SVG or canvas required. Tailwind CSS v4 Gradient Utilities Complete guide to Tailwind v4 gradient utilities. bg-linear-to-r, bg-radial, bg-conic, from-*, via-*, to-*, and in-oklch modifier reference. CSS Gradient Borders Apply CSS gradient borders using border-image or background-clip masking. Both techniques, browser support comparison, and border-radius workaround. OKLCH Interpolation in CSS Gradients Use OKLCH color space interpolation in CSS gradients with the in oklch modifier. How it eliminates grey midpoints and improves perceptual smoothness. CSS Gradients for Dark Mode UI Design CSS gradients for dark mode using reduced chroma, lower lightness stops, and prefers-color-scheme media queries. Practical patterns for UI surfaces. CSS Background Patterns with Gradients Build repeating CSS background patterns using gradient functions and background-size. Stripes, grids, dots, and diagonal tile techniques without images. Glassmorphism with CSS Gradients Implement the glassmorphism effect with CSS gradients, backdrop-filter blur, and translucent stops. Browser support and performance considerations. CSS Gradient Rendering Across Laptop and Phone Displays How CSS gradients render on the Dell XPS 16, iPhone 17 Pro, MacBook Air M4, MacBook Pro M4 and Galaxy S25: P3 color stops, OKLCH interpolation, OLED blacks and the browser engine each device runs.