CSS Gradient Builder: Code Examples

Export Figma Gradients to CSS

Copying CSS gradient code from Figma takes a single click from the Design panel, but understanding what Figma exports and where the format falls short helps you decide when to use the pasted value as-is and when to refine it manually. Selecting a layer with a gradient fill reveals a CSS copy icon next to the fill swatch in the Fill section.

Figma supports three gradient fill types: Linear, Radial, and Angular. Linear corresponds to CSS linear-gradient(); Radial to radial-gradient(); Angular to conic-gradient().¹ Each exports as a CSS-ready string with percentage-based stop positions.² Figma exports stop colors as HEX values regardless of the input color format, which constrains wide-gamut OKLCH colors to the sRGB gamut.³ For paste-ready gradient values that match any Figma geometry, the gradient builder on this page generates equivalent CSS output.

Copying CSS from the Design panel

The copy icon for gradient CSS appears on the Fill row in the Design panel, not in the Code panel.⁴ Hover over the gradient fill swatch row and the icon appears at the right edge of the row. The Code panel in Inspect mode also shows CSS output, but the Fill row copy is the faster path for gradient values specifically since it skips the layout properties and constraints that the Code panel includes alongside the gradient.

The exported CSS includes the full background property, including the shorthand or longhand format Figma uses for the specific gradient type. Pasting directly gives background: linear-gradient(...), which is valid as an inline style or a CSS property value. For use in background-image without the shorthand, remove the background: prefix from the pasted value and keep only the gradient function itself, which is the approach most component-based frameworks expect when you assign gradient values to a dedicated background-image property.

Design panel vs Code panel

The Design panel copy icon gives the background shorthand, which is the most common need. The Code panel in Inspect mode shows the same CSS but also includes layout properties and constraints, which adds noise when you only need the gradient value. Building on this, the Fill row copy is the faster path for gradient values specifically. The Code panel is still useful when you need to inspect other layer properties alongside the gradient, such as opacity, blend mode, or fill rule settings.

Verifying exported stop colors

Consequently, the pasted CSS works immediately in most contexts. Building on this, Figma occasionally outputs intermediate stop colors that represent Figma's own color management conversions rather than the designer's original input colors, which can shift colors slightly for wide-gamut or HSL-specified stops, so a quick visual check in the browser confirms the export matches the design intent.

Always verify the stop colors against the original design values after pasting, especially when the design relies on precise brand color matching or subtle gradient transitions between closely related hues. A practical verification workflow is to paste the exported gradient into a test element, screenshot it, and compare the result side-by-side with the Figma design at the same viewport dimensions to catch any color or positioning discrepancies before committing the value to production stylesheets.

Linear vs Radial vs Angular fill types

Figma's Linear fill corresponds to CSS linear-gradient(). The direction uses the to keyword: to right, to bottom right, or similar. Figma calculates the CSS direction from the gradient handle positions in the design canvas, translating them to a to direction keyword or percentage-based angle. Figma's Radial fill exports as radial-gradient() with an ellipse shape and an at position, while Figma's Angular fill exports as conic-gradient() with a from angle and at position.

Figma's Radial fill exports as radial-gradient() with an ellipse shape and an at position. The position reflects the Figma center handle placement as percentages of the layer's bounding box. Figma's Angular fill exports as conic-gradient() with a from angle and at position, and the from angle reflects the Figma rotation handle position on the canvas.

Yet conic-gradient() CSS support differs slightly from Figma's Angular behavior: Figma's Angular fill can produce effects the browser conic-gradient() replicates only approximately when the Figma center is outside the layer bounds. Building on this, verify Angular gradient exports in the browser's DevTools to confirm they render as expected. When the Figma center handle sits outside the layer bounds, the conic-gradient() at position in CSS places the center at a percentage of the element's bounding box, which may not match Figma's visual result if the design relies on an off-canvas focal point. For designs that depend on precise off-center conic positioning, manually adjusting the at position values in the exported CSS after pasting from Figma gives you pixel-level control that matches the original design intent without needing to rework the Figma source file.

Multi-stop gradients and position accuracy

Figma exports multi-stop gradients with all stop positions as percentages of the gradient line length. Each stop's position in the exported CSS matches its handle placement in Figma at the percentage scale. A stop at 30% in Figma exports as a 30% position in the CSS gradient, so stop positions transfer directly without conversion.

HEX vs OKLCH export limitation

Figma exports all stop colors as HEX regardless of the input format. Colors specified in Figma's OKLCH editor, HSL picker, or oklch() notation all export as HEX approximations. The HEX approximation represents the sRGB equivalent of the input color. For colors within the sRGB gamut, the conversion is lossless in practice. For wide-gamut P3 colors specified in Figma, the HEX export clips to the nearest sRGB value. Consequently, the exported CSS gradient may appear noticeably less saturated than the Figma design when viewed side-by-side on a wide-gamut P3 display. To preserve P3 colors, manually replace the HEX stops with color(display-p3 ...) values in the CSS after copying from Figma.

Notes

Figma panel location: Select a layer with a gradient fill. In the Design panel (right sidebar), locate the Fill section. A gradient swatch appears with the fill type label (Linear, Radial, or Angular). Hover the fill row to reveal a copy icon (two overlapping squares) on the right. Click the copy icon to copy the CSS background property value. For linear gradients, Figma outputs linear-gradient() with to [direction] syntax. For radial, it outputs radial-gradient() with ellipse at [position]. For angular, it outputs conic-gradient() with from [angle] at [position]. All stop colors export as HEX.

Examples

background: linear-gradient(135deg, #e66465 0%, #9198e5 100%);

background: radial-gradient(ellipse at 50% 50%, #e66465 0%, #9198e5 100%);

background: conic-gradient(from 0deg at 50% 50%, #e66465 0%, #9198e5 100%);

Try in the tool

CSS Gradients in React with Tailwind CSS v4

Applying Tailwind CSS v4 gradient utilities in React follows the same patterns as plain HTML, but dynamic gradients require a different approach since Tailwind's JIT engine cannot detect class names constructed at runtime.¹ The v3 bg-gradient-to-* pattern is replaced by bg-linear-to-r, bg-radial, and bg-conic, with direction and type handled by separate utility segments.²

Color stops attach via from-*, via-*, and to-* modifiers, which accept any color token in your palette. The oklch interpolation mode attaches with the /oklch modifier on the gradient type class, enabling perceptual color space blending without writing any custom CSS. For dynamic gradients where stop colors change based on props or state, inline style with a CSS custom property is more practical than constructing class names dynamically.

Gradient utilities in Tailwind v4

Tailwind v4 introduces a cleaner gradient API. Where v3 required bg-gradient-to-r with color stops on separate classes, v4 treats the gradient type and direction as a single utility: bg-linear-to-r, bg-linear-to-br, bg-radial, bg-conic.² Color stops attach with from-violet-500 via-purple-400 to-pink-500. The /oklch modifier enables OKLCH interpolation: bg-linear-to-r/oklch from-blue-500 to-orange-400 produces a vivid blend without the grey midpoint that appears in sRGB.

Direction modifiers cover all eight compass directions and form a predictable pattern. A 45-degree diagonal uses -to-br (bottom-right) or -to-tl (top-left). For precise degree values not in the preset list, use an arbitrary value with the color tokens referenced through the var() function and the component's CSS custom properties. Note the underscore escaping: Tailwind converts underscores to spaces inside arbitrary value brackets.³

Arbitrary values for non-standard gradient angles

Tailwind's preset direction modifiers cover the eight compass points, but many designs call for specific angles such as 135 degrees or 220 degrees. The arbitrary value syntax handles these by placing the full gradient function inside the bracket with underscores replacing spaces. The underscore inside square brackets converts to a space in the compiled CSS, so the output reads as a normal CSS gradient function. This pattern also works for conic and radial gradients with custom parameters that Tailwind does not expose as named utilities.

Because arbitrary values compile to plain CSS, the same bracket syntax works for every gradient function Tailwind ships. A conic or radial with a custom center uses the identical pattern as a linear angle; only the inner function name changes. Underscores still stand in for spaces, so copying a value straight from the CapyToolkit gradient builder into the brackets preserves the exact spacing the tool produced. Keeping dynamic angles in arbitrary values rather than bespoke utilities avoids scattering one-off classes across the component tree.

Dynamic gradients with props and state

Tailwind classes are static strings in source files. The JIT engine scans source files for complete class names; splitting a class across a string concatenation prevents detection and strips it from the output bundle.¹ Dynamic stop colors require either a full set of pre-declared classes (one per possible color) or an inline style approach.

Using CSS custom properties for dynamic stops

The most practical pattern sets a CSS custom property on the element and references it in a fixed class. Define a base gradient class in CSS using custom properties for the start and end colors, then set those properties via the style prop in JSX. The style object assigns the custom properties the runtime color values passed as props. Consequently, the Tailwind class is static and JIT detects it, while the actual colors change at runtime through the custom properties. Furthermore, this pattern works with the browser color picker output from the CapyToolkit gradient builder: paste the CSS value into the variable, and the gradient updates live.

Gradient variants and responsive modifiers

Tailwind's modifier system works on gradient utilities the same way it works on other utilities.⁴ The dark: modifier switches gradient colors in dark mode: dark:from-slate-800 dark:to-slate-900. The hover: modifier changes the gradient on hover: hover:from-violet-600 hover:to-indigo-700. Responsive modifiers apply at breakpoints: md:bg-linear-to-r changes the gradient direction at the medium breakpoint.

Layered modifiers stack left to right: dark:hover:from-violet-700 is valid and applies to the dark-mode hover state.⁴ Building on this, Tailwind's group and peer modifiers work with gradient stops, enabling parent-state-driven gradient changes without any JavaScript. Yet complex dynamic gradients with more than two or three variable stops become unwieldy with class names alone; switch to inline CSS custom properties once the class string grows beyond three dynamic modifiers.

Building a gradient design token system for React component libraries

A gradient token system in a React component library defines gradient values as named constants rather than inline class strings. Exporting a gradients object from a shared tokens file: export const gradients = { brand: 'bg-linear-to-r from-violet-500 to-pink-500', neutral: 'bg-linear-to-r from-slate-400 to-slate-600' } gives every consuming component a single source of truth for gradient class names. Updating a gradient across the library requires changing one entry in the gradients object rather than searching all JSX files for inline class strings.

In Tailwind v4 projects, the token object stores the full class names. In CSS-first projects, the equivalent pattern stores CSS variable assignments. Combining both by defining CSS custom properties in globals.css and pairing them with matching Tailwind arbitrary-value class strings keeps the token system compatible with both Tailwind and plain CSS consumers in the same library.

Storybook integration for gradient visual regression

Adding each gradient token as a Storybook story lets you catch visual regressions across library releases. A story that renders each gradient class on a consistent background makes color and direction changes visible without manual browser testing. Configuring Chromatic or Percy to snapshot gradient stories catches unexpected rendering differences introduced by Tailwind configuration changes or dependency updates before they reach production.

Notes

Tailwind v4 gradient utilities: bg-linear-to-r (left-to-right linear), bg-linear-to-br (diagonal), bg-radial (circular radial from center), bg-conic (conic from 0deg). Direction modifiers: -to-r, -to-l, -to-t, -to-b, -to-tr, -to-tl, -to-br, -to-bl. Stop modifiers: from-{color}, via-{color}, to-{color}. OKLCH interpolation: bg-linear-to-r/oklch. Arbitrary values: bg-[linear-gradient(135deg,_#e66465,_#9198e5)]. The v3 bg-gradient-to-* classes are removed in v4.

Examples

<div className="bg-linear-to-r/oklch from-blue-500 to-orange-400 h-64 rounded-xl" />

function GradientCard({ startColor, endColor }) {
  return (
    <div
      className="h-32 rounded-lg gradient-card"
      style={{ '--from': startColor, '--to': endColor }}
    />
  );
}
// In your CSS:
// .gradient-card { background: linear-gradient(to right, var(--from), var(--to)); }

<h1
  className="text-4xl font-bold bg-linear-to-r from-violet-500 to-pink-500 bg-clip-text text-transparent"
>
  Gradient Heading
</h1>

Try in the tool

CSS Gradient Backgrounds in Next.js

Three distinct approaches exist for applying CSS gradient backgrounds in Next.js, and choosing among them depends on whether the gradient is shared across routes, scoped to a single component, or computed at runtime. globals.css applies gradients site-wide via class names that any component can reference.¹ CSS Modules scope gradients to the component file, preventing style leakage between routes.² The inline style prop applies gradient values directly in JSX.

Each approach has a distinct trade-off: globals.css is easiest to maintain for shared design tokens; CSS Modules are preferred for component-level encapsulation; inline style is necessary when the gradient value changes based on props or fetched data. The App Router and Pages Router handle all three approaches identically since CSS processing does not differ between them.¹

globals.css and Tailwind base layer for site-wide gradient tokens

globals.css is imported once in the root layout or _app.tsx and applies globally. Adding a .hero-gradient class with a gradient background there makes it available to every component without an import. For Tailwind CSS projects, adding CSS custom property definitions to the @layer base rule integrates gradient tokens into the Tailwind token system.

Defining CSS custom properties for gradient stop colors in globals.css allows the stops to adapt to dark mode via prefers-color-scheme or a data-theme attribute. A @layer base block in globals.css defines the start and end color variables in :root, then redefines them inside @media (prefers-color-scheme: dark). Consequently, any component using a linear gradient that references those custom properties automatically adapts to the system color scheme without any JavaScript.³ Building on this, placing gradient token definitions in globals.css keeps them centralized and prevents each CSS Module from duplicating the same stop color values.

Browser support for CSS custom properties in gradient stops

All modern browsers, including the versions of Chrome, Firefox, Safari, and Edge that Next.js projects typically target, support CSS custom properties in gradient functions.³ Internet Explorer 11 does not support custom properties, but Next.js does not support IE11 either, so this is not a concern for any active Next.js project. The var() function works in linear-gradient(), radial-gradient(), and conic-gradient() in every browser that Next.js officially supports. This means any gradient that references a custom property for its stop colors adapts automatically when the custom property value changes, whether through a media query, a class toggle, or a JavaScript assignment.

Sharing gradients with composes

The composes keyword in CSS Modules allows one class to inherit rules from another.² A shared gradient defined in a design-tokens module: .brandGradient { background: linear-gradient(...) }. A component class that composes it: .hero { composes: brandGradient from './design-tokens.module.css'; min-height: 400px; }. The hero class gains the gradient background without duplicating the declaration, and any additional properties applied to the hero class remain scoped to that component alone rather than leaking across the tree.

composes only works within CSS Modules; it cannot compose from globals.css. Class name collisions between CSS Module files are not possible, making the composes approach safe across the component tree. Because the composed class name resolves to a unique identifier at build time, the gradient declaration stays tightly coupled to the component that uses it while still being easy to update in a single place when the brand palette changes.

CSS Modules with composes for gradient reuse

CSS Modules generate locally scoped class names. A .hero class in Hero.module.css applies only to elements using styles.hero in the Hero component. This prevents the gradient from leaking into other components even if they use the same class name. The composes keyword also supports composing from multiple sources in a single declaration, so a component class can inherit a gradient from one module and a typography pattern from another without duplicating either rule.

The composes keyword in CSS Modules allows one class to inherit rules from another. A shared gradient defined in a design-tokens module: .brandGradient { background: linear-gradient(...) }. A component class that composes it: .hero { composes: brandGradient from './design-tokens.module.css'; min-height: 400px; }. Once the hero class gains the gradient background through composition, any additional CSS properties written directly on the hero class remain scoped to that component alone.

composes only works within CSS Modules; it cannot compose from globals.css. Class name collisions between CSS Module files are not possible, making the composes approach safe across the component tree. Because the composed class name resolves to a unique identifier at build time, the gradient declaration stays tightly coupled to the component that uses it while still being easy to update in a single place when the brand palette changes.

The composes keyword also supports composing from multiple sources in a single declaration, so a component class can inherit a gradient from one module and a typography pattern from another without duplicating either rule. This multi-source composition capability makes it straightforward to build a shared design-token module that defines gradients, spacing, and color tokens independently, giving teams a single source of truth that any component can reference through composition rather than through duplicated declarations.

cn() for conditional gradient switching in App Router components

The cn() function (a thin wrapper around clsx and tailwind-merge) builds conditional class strings in JSX. For Tailwind gradient utilities, cn() selects between gradient classes based on a component variant prop: cn('base-class', variant === 'primary' && 'bg-linear-to-r from-violet-500 to-pink-500', variant === 'secondary' && 'bg-linear-to-r from-slate-400 to-slate-600'). tailwind-merge inside cn() resolves conflicting Tailwind utilities correctly, ensuring that the last matching gradient class in the stylesheet order wins predictably without manual specificity management.

tailwind-merge inside cn() resolves conflicting Tailwind utilities correctly. Without tailwind-merge, two bg-linear-to-* classes from different conditions would both appear in the class string, and the last one in the stylesheet order would win unpredictably. Consequently, cn() makes conditional gradient selection safe in a Tailwind project. The deduplication behavior applies to every Tailwind utility in the class list, not just gradient classes, so cn() also prevents accidental overrides for spacing, typography, and color utilities that appear elsewhere in the same className expression.

Server Components in the App Router support cn() for class building: the class string computation happens on the server and the final string appears in the HTML response with no client JavaScript for class logic. For components that need to switch between more than three or four gradient variants, extracting the variant-to-class mapping into a constant object keeps the cn() call readable.

Gradient CSS extraction and critical CSS in Next.js production builds

Next.js extracts CSS into separate chunk files during production builds using the built-in PostCSS and Lightning CSS pipeline. CSS Modules used for gradient styles compile to scoped class names in separate chunks that Next.js loads only when the component importing that module is rendered on the current route. A gradient defined in Hero.module.css loads only when the Hero component is active, reducing the CSS payload on routes that do not include that component.

Gradient classes in globals.css load on every route because globals.css imports to the root layout. Keeping only truly shared gradient tokens in globals.css and moving component-specific gradients into CSS Modules reduces the global CSS bundle size. For gradients used only on the homepage, placing them in a page-specific CSS Module rather than globals.css removes them from the CSS payload of every other route.

Critical CSS and the above-the-fold gradient

Next.js inlines a small amount of critical CSS in the initial HTML response for App Router routes. Hero section gradients defined with CSS Modules appear in the component's CSS chunk rather than the inlined critical CSS, which can cause a brief flash of unstyled content if the chunk loads after the HTML renders. Preloading the CSS Module chunk using the next/link preload pattern, or defining the hero gradient in globals.css, prevents the flash for above-the-fold gradient sections.

Notes

CSS Modules import: import styles from './Component.module.css'. Class reference: className={styles.hero}. cn() utility for conditional gradients: import { cn } from '@/lib/utils'; className={cn(styles.base, variant === 'primary' && styles.primaryGradient)}. Inline style prop: style={{ background: 'linear-gradient(...)' }}. globals.css: add classes in app/globals.css and import it in app/layout.tsx (App Router) or pages/_app.tsx (Pages Router).

Examples

/* in app/globals.css */
:root { --grad-from: oklch(0.85 0.12 250); --grad-to: oklch(0.80 0.10 300); }
@media (prefers-color-scheme: dark) {
  :root { --grad-from: oklch(0.22 0.06 250); --grad-to: oklch(0.18 0.05 300); }
}
.hero-gradient { background: linear-gradient(135deg, var(--grad-from), var(--grad-to)); }

/* Hero.module.css */
.hero {
  background: linear-gradient(to bottom right, oklch(0.75 0.18 250), oklch(0.65 0.15 300));
  min-height: 400px;
}

/* Hero.tsx */
import styles from './Hero.module.css';
export function Hero() {
  return <section className={styles.hero}>{/* content */}</section>;
}

export function GradientBanner({ startColor, endColor, angle = 135 }) {
  return (
    <div
      style={{
        background: `linear-gradient(${angle}deg, ${startColor}, ${endColor})`,
        height: '200px',
      }}
    >
      {/* content */}
    </div>
  );
}

Try in the tool

CSS Gradients in Svelte Components

Component-scoped styles are the default in Svelte, which means CSS written inside a component's style block applies only to that component's elements and prevents gradient styles from leaking into other components or pages.¹ For gradients that need to cross component boundaries, the :global() selector escapes the scoping.¹ Reactive gradient declarations use $: in Svelte 4 or $derived in Svelte 5 to compute gradient strings from reactive state.²

Passing gradient stops as props and applying them via the style attribute handles dynamic runtime gradients without scoping issues. Consequently, Svelte's style system supports both static gradient design tokens and reactive gradient computation with minimal boilerplate. Building on this, the gradient builder on this page outputs CSS values ready to paste into a Svelte style block or a style attribute.

Scoped style blocks and gradient leakage prevention

Svelte compiles style block CSS with a unique class attribute (such as svelte-abc123) added to every element in the component template. This attribute scoping means a .hero rule in one component does not affect .hero elements in another component, even if they share the same class name. Adding a gradient to a component's own elements requires only writing the CSS in the style block with no imports, no module references, and no special syntax needed to keep the styles isolated.

Adding a gradient to a component's own elements requires only writing the CSS in the style block. No imports, no module references, no special syntax: div { background: linear-gradient(to right, oklch(0.75 0.18 250), oklch(0.65 0.15 300)); } applies the gradient to all div elements inside that component and nowhere else. Consequently, gradient styles stay contained to the component that defines them.

How Svelte scoping differs from CSS Modules

CSS Modules achieve scoping by generating unique class names at build time. Svelte takes a different approach: it adds a shared attribute (such as svelte-abc123) to every element in the component template and appends the same attribute to every CSS selector in the style block. The result is the same isolation, but the mechanism is attribute-based rather than class-based.

This means Svelte-scoped styles work even when elements have no class attribute at all, which is useful for styling raw HTML elements like section, header, or div without adding a class. The scoping system prevents one of the most common CSS bugs in multi-component applications: accidental style inheritance across unrelated components that share class names. Because the scoping attribute is added at compile time rather than runtime, there is zero performance cost for style isolation.

Passing gradient stops as props via the style attribute

For dynamic gradient stops that change based on component input, pass the stop colors as props and apply them through the style attribute using CSS custom properties.³ The component declares the props and sets the custom properties on the root element. In the script block, declare the props with export let in Svelte 4 or the $props() rune in Svelte 5, then set custom properties on the element using inline style with the CSS custom property names of your choice.

In the script block, declare the props with export let in Svelte 4 or the $props() rune in Svelte 5, then set custom properties on the element using inline style. In the style block, reference those properties with var() inside the gradient function so the gradient updates whenever the parent passes new values.

Yet the CSS custom property approach requires the parent to pass valid CSS color strings; the component does not validate the format. Building on this, TypeScript type annotations on the props enforce that callers pass string values, though CSS validity checking requires a separate color validation step. The CapyToolkit gradient builder outputs color strings in oklch and HEX format that paste directly into Svelte prop defaults without modification, giving you both runtime flexibility and compile-time safety.

Reactive gradient strings with $: and $derived

Reactive declarations automatically recompute when their dependencies change. In Svelte 4, $: gradient = linear-gradient(to right, ${from}, ${to}) recomputes whenever from or to changes. In Svelte 5, const gradient = $derived(...) replaces the $: syntax with a rune.² Either approach updates the gradient string reactively from store values, props, or local state. Combining a Svelte writable store for theme colors with a reactive gradient string produces a gradient that responds to global theme changes without any additional boilerplate or manual event wiring.

Comparing reactive gradient approaches

The style attribute approach sets the full gradient string directly on the element, which is the simplest pattern for a gradient that depends on only one or two reactive values. The CSS custom property approach keeps the gradient definition in the style block and only updates the stop color variables, which scales better when multiple properties of the same gradient change independently.

Computed gradients from store values

Combining a Svelte writable store for theme colors with a reactive gradient string produces a gradient that responds to global theme changes. When the theme store updates the from and to values, the reactive declaration recomputes the gradient string, and the template re-renders with the new value. Consequently, a theme toggle that writes new color values to the store propagates automatically to every component with a reactive gradient.

Furthermore, Svelte's fine-grained reactivity means only the elements using the gradient variable re-render, which becomes especially valuable in complex dashboards where multiple gradient-driven visualizations update at different frequencies since a color change in one chart does not trigger unnecessary re-renders in sibling components. This surgical update behavior keeps the component tree stable and avoids layout thrashing even when several gradient values change in rapid succession during user interactions or animated transitions.

Notes

Svelte scoped style: Add CSS inside the <style> block of any .svelte file. Svelte auto-scopes to the component. :global() syntax: :global(.hero) { background: linear-gradient(...); } applies without scoping. Reactive gradient string in Svelte 4: $: gradient = 'linear-gradient(to right, ' + from + ', ' + to + ')'; Svelte 5: const gradient = $derived('linear-gradient(to right, ' + from + ', ' + to + ')'); Apply via style attribute: style="background: {gradient}". CSS custom property prop: define a custom property on the element via the style attribute, then reference it with var() in the style block. When using custom properties for gradient stops, the property names are arbitrary; choose names that describe the purpose, such as panel-start and panel-end for a panel component.

Examples

<div class="hero">
  <slot />
</div>

<style>
  .hero {
    background: linear-gradient(135deg, oklch(0.75 0.18 250), oklch(0.65 0.15 300));
    min-height: 400px;
  }
</style>

<script>
  let { from = 'oklch(0.75 0.18 250)', to = 'oklch(0.65 0.15 300)' } = $props();
  const gradient = $derived(`linear-gradient(to right, ${from}, ${to})`);
</script>

<div style="background: {gradient}; height: 200px;"></div>

<div class="panel">
  <slot />
</div>

<style>
  .panel {
    background: linear-gradient(to bottom, var(--panel-from), var(--panel-to));
  }
  /* Allow parent to override via :global() */
  :global([data-theme="dark"]) .panel {
    --panel-from: oklch(0.18 0.04 250);
    --panel-to: oklch(0.14 0.02 250);
  }
</style>

Try in the tool

CSS Gradients in Vue.js 3 Components

Vue.js 3 gives developers three distinct tools for managing CSS gradients in Single File Components, and each one addresses a different aspect of the styling workflow. Scoped styles with style scoped restrict gradient CSS to the component, preventing leakage. The v-bind() function in CSS (Vue 3.2+) binds a reactive JavaScript value directly into a CSS property value.¹ The Composition API's computed() function assembles complex gradient strings from multiple reactive refs.

Together these features give Vue developers complete control over both static and dynamic gradients without global class name management. Consequently, gradient colors defined in JavaScript can drive CSS directly without template string interpolation in the style attribute. Building on this, the gradient builder on this page outputs CSS gradient values that paste directly into Vue style blocks or computed() string templates.

Static gradient in a scoped style block

Style scoped restricts CSS to the current component by adding a unique data attribute to both the HTML elements and the CSS selectors at compile time. A gradient in a scoped style block: .hero { background: linear-gradient(to right, oklch(0.75 0.18 250), oklch(0.65 0.15 300)); } applies only to .hero elements inside this component's template.² Scoped styles prevent gradient declarations from affecting sibling or parent components, which is especially useful when multiple components define a .hero or .card class with different gradient values.

Scoped styles prevent gradient declarations from affecting sibling or parent components. This is especially useful when multiple components define a .hero or .card class with different gradient values: each component's gradient stays independent. Consequently, scoped styles are the recommended approach for component-level gradient design in Vue. Building on this, the gradient builder outputs a CSS value that pastes directly into a scoped style rule without any Vue-specific modification, so the gradient syntax is identical to plain CSS and works across frameworks.

Scoped style limitations and deep selectors

The scoped attribute adds a data attribute to every element in the component template. Child components rendered inside the parent do not receive the parent's scoped attribute on their root element, which means parent scoped styles cannot target child component roots directly. The deep selector (:deep() or the older ::v-deep) overrides this limitation: :deep(.child-class) { background: linear-gradient(...) } applies the gradient to elements inside child components.² Use deep selectors sparingly since they partially break the encapsulation that scoped styles provide.

Building on this, the gradient builder outputs a CSS value that pastes directly into a scoped style rule without any Vue-specific modification; the gradient syntax is identical to plain CSS and works across frameworks so the same gradient value can be shared across a multi-framework design system without any framework-specific adaptation or string manipulation.

v-bind() in CSS for reactive stop colors

Vue 3.2 introduced v-bind() inside <style> blocks, allowing JavaScript reactive values to appear directly in CSS property values. Declare a reactive ref for each dynamic stop: const fromColor = ref('oklch(0.75 0.18 250)'). In the style block: .hero { background: linear-gradient(to right, v-bind(fromColor), oklch(0.65 0.15 300)); }. When fromColor updates in the script, Vue injects the new value into the CSS custom property that v-bind() creates internally, and the gradient updates reactively without any template-level style binding.¹

When fromColor updates in the script, Vue injects the new value into the CSS custom property that v-bind() creates internally. The gradient updates reactively without any template-level style binding. Vue compiles v-bind() into a hashed CSS custom property applied to the component's root element via inline styles, and the value updates whenever the bound ref changes. This per-instance scoping means that two instances of the same component can display different gradient colors simultaneously without interfering with each other, which is particularly useful for reusable card or banner components that accept different color props in different contexts on the same page.

computed() gradient string for multi-stop gradients

The computed() function in the Composition API builds a derived value that updates when any of its reactive dependencies change. For a complex multi-stop gradient, assembling the string in computed() keeps the template clean and makes the gradient logic testable in isolation.³ Wrapping the computed gradient in a composable (useGradient) makes the pattern reusable across multiple components with different initial stop values, and the composable can return both the computed gradient string and setter functions for updating colors programmatically.

Computed gradient with multiple refs

const from = ref('oklch(0.75 0.18 250)'); const via = ref('oklch(0.70 0.16 275)'); const to = ref('oklch(0.65 0.15 300)'); const gradient = computed(() => 'linear-gradient(to right, ' + from.value + ', ' + via.value + ', ' + to.value + ')'). Apply it in the template: :style="{ background: gradient.value }". Consequently, any update to from, via, or to causes gradient to recompute and the element style to update. Building on this, wrapping the computed gradient in a composable (useGradient) makes the pattern reusable across multiple components with different initial stop values. The composable can accept default stop colors as parameters and return both the computed gradient string and setter functions, giving consuming components a clean API for updating gradient colors programmatically while keeping the string assembly logic centralized and testable.

Animating between gradient states with watch() and CSS transitions

Vue's Transition component handles CSS class-based animations when elements enter or leave the DOM, but it does not directly animate changes to background gradient values on persistent elements. For a gradient that changes state on user interaction, the watch() function in the Composition API detects when a reactive ref changes and can trigger a class swap or custom property update that CSS transitions act on.

Setting transition: background 0.4s ease on the element in the scoped style block enables CSS transitions when the background property changes. However, the CSS background-image property has a discrete animation type, so browsers cannot interpolate between two gradient values without @property.⁴ Consequently, transitioning between two gradient states without @property produces an abrupt switch at the animation midpoint. Assigning the gradient stop colors to typed @property registered properties and transitioning those values instead produces smooth gradient state transitions.⁵

Using class switching for discrete gradient states

For a small set of gradient states such as two or three variants, switching CSS classes is a simpler pattern than animating individual stop values. Define .gradient-default and .gradient-active in the scoped style block with different stop colors. Use Vue's :class binding to toggle between them and add CSS transition: background 0.3s ease on the element. The transition fires on class change, but without @property it snaps rather than blends between the gradient values.

Notes

Scoped style: <style scoped>. v-bind() in CSS: const color = ref('oklch(0.7 0.2 250)'); then in the style block: background: linear-gradient(to right, v-bind(color), blue). computed() gradient: const gradient = computed(() => 'linear-gradient(to right, ' + from.value + ', ' + to.value + ')') applied via :style="{ background: gradient }". Vue 3.2+ required for CSS v-bind(). All Vue 3 versions support computed() and :style.

Examples

<template>
  <div class="hero"></div>
</template>

<style scoped>
.hero {
  background: linear-gradient(135deg, oklch(0.75 0.18 250), oklch(0.65 0.15 300));
  min-height: 400px;
}
</style>

<script setup>
import { ref } from 'vue';
const fromColor = ref('oklch(0.75 0.18 250)');
const toColor = ref('oklch(0.65 0.15 300)');
</script>

<template>
  <div class="banner"></div>
</template>

<style scoped>
.banner {
  background: linear-gradient(to right, v-bind(fromColor), v-bind(toColor));
  height: 200px;
}
</style>

<script setup>
import { ref, computed } from 'vue';
const from = ref('oklch(0.75 0.18 250)');
const to = ref('oklch(0.55 0.18 300)');
const angle = ref(135);
const gradient = computed(
  () => `linear-gradient(${angle.value}deg, ${from.value}, ${to.value})`
);
</script>

<template>
  <div :style="{ background: gradient }"></div>
</template>

Try in the tool

CSS Gradients in styled-components

Styled-components uses tagged template literals to write CSS directly in JavaScript. A gradient background applies the same way as in a plain CSS file, inside the backtick string of a styled component.¹ The css helper extracts reusable gradient fragments to a shared file, making the same gradient importable across multiple components without duplication.² ThemeProvider integration passes theme color tokens as stop values, enabling gradients that adapt to the active theme without prop drilling.³ Props-based gradient switching conditionally changes the gradient based on the component's runtime props.¹ Consequently, styled-components supports every CSS gradient use case while adding JavaScript-level composition and type safety when combined with TypeScript. Building on this, the gradient builder on this page outputs CSS gradient values that paste directly into the backtick string of any styled component without modification.

Inline gradient in a styled component

A gradient background in a styled component uses the same CSS syntax as a plain stylesheet, inside the template literal string. The template literal interpolation ${ } embeds JavaScript expressions, which enables theme token references and prop-based values inline with the CSS. A static gradient definition compiles to a class at runtime, and the gradient can be inspected in the browser DevTools under a generated class name that is a deterministic hash of the template literal content.⁴

A static gradient: const Hero = styled.div'background: linear-gradient(135deg, oklch(0.75 0.18 250), oklch(0.65 0.15 300)); min-height: 400px;'. The backtick string is valid CSS and styled-components compiles it to a class at runtime. Consequently, the gradient can be inspected in the browser DevTools under a generated class name. Building on this, styled-components generates unique class names per component definition, so two Hero components with different gradients in their template literals produce two distinct class names without conflict. The class names are deterministic hashes of the template literal content, meaning identical gradient definitions across different component files share the same generated class, which deduplicates the CSS output in the final bundle.

The css helper for reusable gradient fragments

The css helper from styled-components creates a fragment of CSS that can be imported and composed into multiple styled components. A gradient fragment file defines the gradient once and exports it: const brandGradient = css'background: linear-gradient(to right, oklch(0.75 0.18 250), oklch(0.65 0.15 300));'. Components import it and spread it into their template literal. The css helper enables nested interpolations with theme token references and conditional expressions inside the fragment, which still resolve correctly when the fragment is composed into a parent template literal at build time.²

Why not a plain string

Plain template literal strings work for simple gradient values. Yet the css helper enables nested interpolations: theme token references and conditional expressions inside the fragment still resolve correctly when the fragment is composed into a parent template literal. Without the css helper, nested interpolations in a plain string fail to process. Furthermore, the css helper provides TypeScript inference for styled-components' theme type, so theme property access inside the fragment benefits from type checking. Consequently, prefer the css helper whenever the gradient fragment contains any interpolated JavaScript expression. For gradient fragments that are entirely static with no theme or prop references, a plain const string works just as well and avoids the minimal overhead of the css helper wrapper, keeping the code as simple as possible for the straightforward cases.

Because the css helper is required as soon as a fragment contains any interpolation, the simplest mental model is to default to css for every shared fragment and reserve a plain const only for throwaway inline values. That keeps one import pattern across the reusable gradients instead of mixing two styles. CapyToolkit's gradient builder outputs a plain CSS value, so pasting it into either a css fragment or a plain const string works without adjustment.

ThemeProvider and props-based gradient switching

ThemeProvider wraps the component tree and passes a theme object through React context. Styled components access the theme via the ({ theme }) => theme.property interpolation pattern inside the template literal. Gradient stop colors from the theme: const Hero = styled.div'background: linear-gradient(to right, ${ ({ theme }) => theme.colors.gradFrom }, ${ ({ theme }) => theme.colors.gradTo });'. A component variant prop changes the gradient based on the prop value, and styled-components regenerates the class on each distinct prop combination and caches the result for subsequent renders.³

Props-based conditional gradient

A component variant prop changes the gradient based on the prop value: const Button = styled.button'background: ${ ({ variant }) => variant === "primary" ? "linear-gradient(to right, oklch(0.75 0.18 250), oklch(0.65 0.15 300))" : "linear-gradient(to right, oklch(0.5 0.05 0), oklch(0.45 0.04 0))" };'. Styled-components regenerates the class on each distinct prop combination and caches the result. Yet generating many distinct gradient variations through props creates many class names; for a large number of gradient options, CSS custom properties with ThemeProvider tokens scale better than individual class generation. A hybrid approach works well in practice: use props-based switching for a small set of named variants like primary and secondary, then fall back to CSS custom property overrides for fully dynamic colors that come from user input or API data at runtime.

Server-side rendering of gradient styles and class hydration

Server-side rendering with styled-components requires the ServerStyleSheet API to collect styles from the component tree into the initial HTML response. Without this step, the server renders HTML with component class names but no corresponding CSS, causing a flash of unstyled gradient content until the client bundle loads and generates the classes. Wrapping the SSR render in ServerStyleSheet.collectStyles() and injecting the result with StyleSheetManager ensures gradient CSS is present in the HTML from the first byte.⁵

Next.js users integrating styled-components with the App Router add the styled-components registry pattern from the Next.js documentation. This pattern wraps the root layout in a client component that collects server-rendered styles and injects them before the server HTML flushes. Gradient classes defined in styled components then appear in the server HTML without a separate CSS file or flash of unstyled content.

Class deduplication across multiple renders

styled-components deduplicates class names across the component tree during both client and server rendering. Two Hero components with the same gradient template literal generate the same hash and share one class name in the compiled stylesheet.⁴ The deduplication applies to both static gradients and ThemeProvider-resolved gradients, as long as the resolved CSS string is identical. Prop-based gradients that produce different resolved strings generate separate classes, each cached independently for subsequent renders.

Notes

Template literal syntax: const Hero = styled.divbackground: linear-gradient(to right, ${theme.colors.from}, ${theme.colors.to});. The css helper: import { css } from 'styled-components'; const gradientFragment = cssbackground: linear-gradient(...);. ThemeProvider token access: ${({ theme }) => theme.colors.primary}. Props-based switching: ${({ variant }) => variant === 'primary' ? 'linear-gradient(...)' : 'linear-gradient(...)'}. TypeScript theme type: declare module 'styled-components' { export interface DefaultTheme { colors: { from: string; to: string; } } }.

Examples

import styled from 'styled-components';

const Hero = styled.div`
  background: linear-gradient(
    135deg,
    oklch(0.75 0.18 250),
    oklch(0.65 0.15 300)
  );
  min-height: 400px;
`;

import { css } from 'styled-components';

export const brandGradient = css`
  background: linear-gradient(to right, ${({ theme }) => theme.colors.from}, ${({ theme }) => theme.colors.to});
`;

// In another file:
import styled from 'styled-components';
import { brandGradient } from './gradients';

const Card = styled.div`
  ${brandGradient}
  border-radius: 12px;
  padding: 24px;
`;

import styled from 'styled-components';

interface ButtonProps { variant: 'primary' | 'secondary'; }

const Button = styled.button<ButtonProps>`
  background: ${({ variant }) =>
    variant === 'primary'
      ? 'linear-gradient(to right, oklch(0.75 0.18 250), oklch(0.65 0.15 300))'
      : 'linear-gradient(to right, oklch(0.5 0.05 0), oklch(0.45 0.04 0))'
  };
  padding: 12px 24px;
  border: none;
  cursor: pointer;
`;

Try in the tool

CSS Gradient Mixins and Functions in SCSS

SCSS mixins and functions make CSS gradients reusable and configurable. A @mixin encapsulates the full gradient declaration with configurable parameters for stop colors and direction.¹ A @function computes stop positions mathematically, enabling programmatic even distribution of N stops across the gradient axis.² An @each loop generates a set of gradient classes from a color map, producing an entire palette of gradient utilities from a single declaration block.³ Output uses either direct background-image declarations or CSS custom property assignments, depending on whether the gradient needs JavaScript-level interactivity at runtime.⁴ Consequently, SCSS-based gradient systems scale from a single reusable mixin to a full design-system gradient API. Building on this, compiling SCSS to CSS with custom property output gives the benefits of SCSS authoring while keeping the runtime flexibility of CSS variables for theme switching.

Basic @mixin and @include usage

A gradient mixin with default direction parameter reduces gradient declarations to a single @include line, which simplifies stylesheet maintenance across a large codebase. Declare the mixin with parameters for the stop colors and an optional direction: @mixin gradient($from, $to, $direction: to right). Inside the mixin body: background-image: linear-gradient($direction, $from, $to). Call it with @include gradient(oklch(0.75 0.18 250), oklch(0.65 0.15 300)) for the default direction, or @include gradient(oklch(0.75 0.18 250), oklch(0.65 0.15 300), 135deg) for a custom angle. Adding additional parameters extends the mixin without breaking existing call sites, so a $via parameter for a midpoint stop defaults to null and the mixin conditionally includes it only when provided. This default-null pattern keeps the public mixin signature stable even as the internal feature set grows.

Adding additional parameters extends the mixin without breaking existing call sites. A $via parameter for a midpoint stop defaults to null; the mixin conditionally includes it only when provided.¹ Consequently, the mixin interface stays clean for simple two-stop calls while supporting three-stop gradients when needed. Each optional parameter has a sensible default so that the simplest @include call works without any configuration, while advanced use cases can opt in to additional behavior without breaking existing call sites across the codebase.

This extensibility pattern is what makes SCSS mixins a practical alternative to utility class systems for gradients, because a single mixin call can express an arbitrarily complex gradient without the stylesheet author needing to remember class name conventions for every combination of direction and stop count, and modifying the mixin definition automatically propagates the change to every call site.

Default parameters and mixin extensibility

SCSS default parameter values mean any call site that omits a parameter automatically gets the intended default behavior, reducing the chance of inconsistency across the codebase. A well-designed gradient mixin starts with the two required color parameters and adds optional parameters for direction, via stop, and custom property emission. Each new optional parameter added after the initial release preserves backward compatibility, because existing call sites that omit the new parameter fall back to the default without any change to their source code.

Each optional parameter has a sensible default so that the simplest @include call works without any configuration, while advanced use cases can opt in to additional behavior. This pattern keeps the mixin backward-compatible as the design system grows. When a new gradient requirement emerges, extending the mixin with additional optional parameters means existing @include calls continue to work without modification while new call sites can opt into the expanded feature set.

@function for calculated stop positions

SCSS @function computes values that SCSS expressions cannot express directly. For a multi-stop gradient where N colors must distribute evenly, a function calculates each stop's percentage position from its index and the total count. Using sass:math for division, the function returns a calculated percentage for any stop index, enabling programmatic even distribution of N stops across the gradient axis without manual position calculations.

Using sass:math for division: @function stop-position($index, $total) { @return math.div($index - 1, $total - 1) * 100%; }.⁵ Calling it for a five-stop gradient: stop-position(1, 5) returns 0%, stop-position(3, 5) returns 50%, stop-position(5, 5) returns 100%. These computed percentages replace the manual position values that would otherwise need to be calculated and hardcoded for each stop in the gradient declaration, which becomes impractical for palettes with more than three or four colors.

Yet SCSS @function cannot accept a variable-length argument list for the color values and loop through them in a single expression; the gradient construction still requires a list variable.² This means the function handles the math while a separate @each loop assembles the final gradient declaration from the computed positions. Building on this, combining @function position calculation with a @each loop that builds the stop list enables a fully programmatic multi-stop gradient assembly from a SCSS color list. You can take this further by defining a master color palette map and a @mixin that accepts a palette name, looks up the colors automatically, and generates the complete gradient with evenly distributed stops, eliminating the need to manually specify stop positions for each new gradient variant.

@each loop for palette gradient variant generation

A SCSS map pairs gradient names with stop color lists. An @each loop iterates the map and outputs one gradient class per entry. This generates an entire set of gradient utilities from a single loop declaration. Adding a new gradient to the map generates a new class automatically on the next SCSS compile without modifying the loop, and extending the map with a third stop value requires only updating the stop list.

Map and loop pattern

$gradients: (primary: (oklch(0.75 0.18 250), oklch(0.65 0.15 300)), secondary: (oklch(0.6 0.1 100), oklch(0.5 0.08 80))); @each $name, $stops in $gradients { .gradient-#{ $name } { background-image: linear-gradient(to right, $stops...); } }. The ... spread operator passes the list items as positional arguments to linear-gradient(). Consequently, adding a new gradient to the map generates a new class automatically on the next SCSS compile without modifying the loop. Furthermore, extending the map with a third stop value requires only updating the stop list; the loop and the gradient function handle the additional stop without any change to the loop body.

This pattern scales to an arbitrary number of gradient variants: adding a new entry to the map with a new name and color list produces a new utility class on the next SCSS compile, making it trivial for the design team to expand the gradient system without touching the loop logic or understanding the underlying SCSS iteration mechanics.

Generating CSS custom property output from SCSS gradient mixins

SCSS mixins can output CSS custom property declarations alongside direct background-image rules, giving consuming components a choice between applying the gradient directly or receiving the stop colors as runtime-accessible variables. A mixin that outputs both assigns the SCSS variables to named custom properties using interpolation, then references those properties in the gradient background-image declaration.

The #{} interpolation is required when assigning a SCSS variable to a CSS custom property. Without interpolation, SCSS parses the assignment as a SCSS variable declaration rather than a CSS property and does not emit it to the compiled output.⁴ After compilation, the result contains both the custom property declarations and the gradient background-image declaration using those properties. JavaScript can then read those custom properties with getComputedStyle() or override them dynamically on the element.

Conditional mixin output for design token systems

Adding a $emit-vars parameter to the mixin lets call sites opt in to the custom property output: the mixin conditionally emits the custom properties only when the parameter is true. Components that need JavaScript interactivity pass true as the fourth argument; components that do not need runtime override call the mixin without the parameter, keeping the compiled CSS minimal across the codebase.

Notes

Basic mixin: @mixin gradient($from, $to, $direction: to right) { background-image: linear-gradient($direction, $from, $to); }. Usage: @include gradient(oklch(0.75 0.18 250), oklch(0.65 0.15 300), 135deg). @function for stop positions: @function stop-position($index, $total) { @return math.div($index - 1, $total - 1) * 100%; }. @each loop: @each $name, $stops in $gradient-map { .gradient-#{$name} { background-image: linear-gradient(to right, $stops...); } }. CSS custom property output: a mixin can emit named custom properties for the start and stop colors using #{} interpolation to assign SCSS variables to CSS variable names.

Examples

@use 'sass:math';

@mixin gradient($from, $to, $direction: to right) {
  background-image: linear-gradient($direction, $from, $to);
}

.hero {
  @include gradient(oklch(0.75 0.18 250), oklch(0.65 0.15 300), 135deg);
  min-height: 400px;
}

.button-primary {
  @include gradient(oklch(0.7 0.22 250), oklch(0.6 0.2 280));
  padding: 12px 24px;
}

@use 'sass:math';

@function stop-pos($index, $total) {
  @return math.div($index - 1, $total - 1) * 100%;
}

$palette: oklch(0.8 0.15 250), oklch(0.7 0.18 270), oklch(0.6 0.2 290), oklch(0.5 0.18 310);

.spectrum {
  background-image: linear-gradient(
    to right,
    nth($palette, 1) #{stop-pos(1, 4)},
    nth($palette, 2) #{stop-pos(2, 4)},
    nth($palette, 3) #{stop-pos(3, 4)},
    nth($palette, 4) #{stop-pos(4, 4)}
  );
}

$gradients: (
  "primary":   (oklch(0.75 0.18 250), oklch(0.65 0.15 300)),
  "secondary": (oklch(0.6 0.1 100),   oklch(0.5 0.08 80)),
  "warm":      (oklch(0.8 0.18 50),   oklch(0.7 0.2 20)),
);

@each $name, $stops in $gradients {
  .gradient-#{$name} {
    background-image: linear-gradient(to right, $stops...);
  }
}

Try in the tool