CSS Gradient Text with background-clip

CSS Gradient Text with background-clip

Gradient text is a masking technique rather than a special text feature. Setting background-image to any gradient function defines the fill, and background-clip: text restricts that fill to the text outlines rather than the full element box.¹ Without background-clip: text, the gradient appears behind the text like any background; with it, the gradient shows through the letterforms only, treating each character as a mask.

The text color itself must be transparent to let the background show through. Omitting transparent leaves the text color painted over the gradient, hiding the effect entirely. This technique uses only stable CSS properties and requires no JavaScript. All major browsers have supported background-clip: text for several years, though the property still requires the -webkit- prefix in older WebKit contexts.

Copying a gradient from a design tool and applying it as text fill takes only the three CSS properties described below, making this one of the fastest visual upgrades you can add to a heading or product name. The CSS Gradient Builder on this page outputs the background-image value ready to paste into your stylesheet.

The three-property pattern

Three properties produce gradient text: background-image sets the gradient, background-clip: text clips the gradient to letterforms, and color: transparent lets the background show through.¹ Applying background-clip: text without color: transparent produces no visible change because the browser paints the text color over the background. Consequently, the order of properties in the stylesheet does not matter, but all three must be present.

Browser prefix handling

The -webkit-background-clip: text declaration is still required for broad WebKit compatibility. Modern build tools include it automatically via autoprefixer. If you hand-write the CSS, write both -webkit-background-clip: text and background-clip: text. Similarly, write both -webkit-text-fill-color: transparent and color: transparent to cover older Safari versions that do not honor the standard property name for text fill color. When you build a reusable heading component, keep the prefixed and standard declarations together so future edits do not accidentally remove one half of the masking pair.

Accessibility and inline element scope

background-clip: text has no inherent accessibility problem: screen readers read the text normally and the visual appearance does not affect announced content. However, gradients with insufficient contrast between the text color and the page background can fail WCAG contrast checks. The gradient stops may pass contrast at one end of a word and fail at the other. Test contrast across the full range of the gradient, not just at a midpoint.

Gradient text works on block and inline elements. Applying it to a span inside a paragraph scopes the gradient to that span's content box. Because the background starts at the element's origin, a short inline span clips only a portion of the gradient, which can produce unexpected color results when the span is near the end of a line. Building on this, prefer applying gradient text to heading elements with predictable widths rather than arbitrary inline spans. The background-image origin anchors to the element's content box, so a span that wraps only the last few words of a sentence shows only the tail end of the gradient rather than the full color range.

Contrast testing workflow

Check the lightest and darkest stops against the actual background, not a neutral placeholder. A heading on a dark hero may pass at the bright edge and fail at the dark edge, while a card label may do the opposite. If either extreme fails, narrow the lightness range, add a subtle text shadow, or place the heading on a solid panel, then adjust the gradient until both ends pass contrast before exporting the final value. Running a contrast check at every 10% position along the gradient catches failures that a single midpoint check misses, especially for gradients that pass through a wide lightness range from dark to bright.

Animating gradient text

Two practical approaches exist for animating gradient text, each with distinct trade-offs in browser support and visual quality. Choosing between them depends on whether you need to move the gradient across the letterforms or change the stop colors themselves. background-position animation shifts a wider gradient horizontally through the text mask and works in every modern browser without any custom property registration, while @property color interpolation enables direct stop color animation but requires Houdini API support in the browser.

Background-position animation

Background-position animation is the most performant method for animating gradient text. Set a background-size larger than the element, such as 200% 100%, and animate background-position with a CSS @keyframes rule. This slides the gradient across the letterforms without triggering layout or paint operations beyond the background layer, which keeps the animation smooth even on lower-powered devices.² The technique works by painting a gradient wider than the element and then shifting which portion of the gradient is visible through the text mask, so the compositor handles the animation on the GPU without involving the main thread on each frame.

The technique works by painting a gradient wider than the element and then shifting which portion of the gradient is visible through the text mask. Because the browser only repositions an existing texture rather than repainting the gradient on each frame, the compositor can handle the animation on the GPU without involving the main thread. Consequently, background-position animation is the recommended starting point for gradient text animation unless you need to interpolate the stop colors themselves.

@property color interpolation

The @property approach offers more control. Registering a custom property as a color with @property allows direct color interpolation between gradient stops in a @keyframes rule.³ Without @property, the browser cannot interpolate between two background-image values and snaps between them at 50% of the transition. Furthermore, the @property method supports OKLCH color interpolation in the animation keyframes, enabling smooth hue travel around the OKLCH color wheel rather than the dull sRGB path through grey.

Reduced motion and static fallbacks

Both animation techniques are continuous motion, so they need a motion-aware fallback rather than an unconditional animation. The prefers-reduced-motion media query reports whether the user has asked the system to minimise non-essential animation, and the recommended pattern is to run the gradient animation only when that query does not match.⁴ Wrapping the animation assignment in @media (prefers-reduced-motion: no-preference) keeps the effect for everyone else while leaving the heading as static gradient text for users who opted out.

Why a static fallback is also the print fallback

Print stylesheets and forced-colors modes both flatten animated backgrounds, which means the heading can end up rendered as transparent text on an empty box, since color: transparent and background-clip: text together assume a painted background exists. A fallback that restores a solid color value under @media print keeps the heading legible in exported PDFs and screenshots, and the same rule doubles as the reduced-motion fallback. The practical structure is a base rule with transparent fill, an animation applied only inside a no-preference media query, and a print override that restores a solid text color.

Contrast carries over to the fallback

Whichever way the heading is rendered, the contrast requirement is the same: 4.5:1 for normal text and 3:1 for large-scale text, where large scale means at least 18pt or 14pt bold.⁵ Because the criterion measures contrast rather than hue, a gradient that looks vivid can still fail at its lighter end, so the same per-stop check that catches the animated version catches the static one.

When to use this

Use gradient text for hero headings, product names, and decorative labels where a single flat color is not enough. Avoid it on body text: the technique reduces legibility at small sizes and fails contrast checks on complex gradients.

Examples