HTML & CSS

Animate a Radial Gradient Radius with a Typed Property

Animate a CSS radial gradient radius using a registered length property, inspect intermediate values, and provide a static reduced-motion version of the effect.

By Uddhav Gopani, FounderPublished 27 September 2026Updated 29 September 2026

Animate a numeric radius instead of replacing images

A radial-gradient animation can change the radius of its color field while keeping the center fixed. Register a custom property as a length, use that property in the radial-gradient() radius, and animate its numeric value. The browser then interpolates a typed length rather than switching between unrelated image strings.

This recipe requires support for typed custom-property registration through @property. Without that registration, an ordinary custom property does not automatically gain smooth length interpolation. Check the browsers your project supports; do not assume that a browser accepting var() also supports this animation technique.

Register the radius and expand it once

The example expands a circular color field from forty-eight to one hundred twenty pixels over four seconds, then holds its final state. It is a decorative introduction beside a static label, not a loading indicator or a measurement of progress. The element’s width and height remain fixed while the radius changes inside it.

<figure class="radius-demo">
  <div class="radius-field"></div>
  <figcaption>A circular color field expands once.</figcaption>
</figure>

@property --demo-radius {
  syntax: "<length>";
  inherits: false;
  initial-value: 48px;
}
.radius-demo { max-width: 28rem; margin: 1rem auto; }
.radius-field {
  --demo-radius: 48px;
  height: 16rem;
  background-color: #0f172a;
  background-image: radial-gradient(
    circle var(--demo-radius) at center,
    #38bdf8 0%, #0f172a 100%
  );
  animation: radius-arrive 4s linear 1 forwards;
}
.radius-demo figcaption { padding-block: .75rem; }
@keyframes radius-arrive { to { --demo-radius: 120px; } }
@media (prefers-reduced-motion: reduce) {
  .radius-field { animation: none; --demo-radius: 120px; }
}

The registration includes a syntax, an inheritance choice and an initial value. Here the initial value is an absolute length, so it does not depend on the element’s font size. The explicit declaration on .radius-field also makes the intended starting value visible next to the rule that uses it.

Predict and inspect the intermediate radius

With linear timing, the halfway radius is eighty-four pixels: forty-eight plus half of the seventy-two-pixel change. At one second it is sixty-six pixels, and at three seconds it is one hundred two. Inspect the computed --demo-radius value while pausing the animation timeline at those times to confirm smooth interpolation.

For a second experiment, change the endpoint from one hundred twenty to one hundred eighty pixels. The midpoint should become one hundred fourteen pixels. The element still has the same layout dimensions; only the position where the gradient reaches its final stop moves outward.

Keep the support requirement explicit

MDN’s @property reference describes typed registration and its required descriptors. Review its compatibility information for your actual browser targets. If a required browser lacks this capability, use a static radius or a separate transform-based decorative layer for that target instead.

Do not claim that the example automatically supplies a smooth fallback in an engine that ignores the registration. An unregistered custom-property animation may change discretely, producing a jump. If a static fallback is part of your support policy, omit the animation in the corresponding delivered stylesheet rather than leaving an unverified partial implementation enabled.

Choose a useful nonanimated state

The reduced-motion rule uses the final radius immediately. That gives the static version a complete composition instead of freezing at a small introductory spot. The text label remains outside the gradient, so neither animation state nor motion preference changes its background or readability.

The four-second single iteration is intentional. If you adapt the effect into a continuous loop, consider whether visitors need an independent pause control and whether repeated motion is appropriate. Increasing the iteration count changes the experience even when all the same CSS primitives remain in use.

Use the generator within its actual scope

The CSS Gradient Generator can help compare a static two-color radial palette. It does not register custom properties, expose a pixel radius or export animation timelines. The radius and timing in this guide are hand-authored CSS, so copying a tool declaration alone will not reproduce the expanding effect.

If the radius jumps, check the registration name, syntax and descriptor validity. If nothing paints, confirm that the element has dimensions and that the variable resolves to a nonnegative length. Test at phone and desktop widths: a fixed pixel radius occupies a different proportion of a wide box, which may be correct for a spotlight but unsuitable for a full-surface fill.