Typed Custom Properties with @property
@property is a CSS at-rule that lets you register a custom property along with a type for it. Normally a custom property is just a string to the browser, so it can't be transitioned or animated. Once you register a type, the browser has the context to interpolate that value over time. That interpolation is the feature's real payoff.
Browser support is still limited at the time of writing: @property works in Chrome and, by extension, Edge. Firefox and Safari are not there yet, so keep an eye on the support tables.
Type checking comes first
@property --spinAngle {
/* An initial value for our custom property */
initial-value: 0deg;
/* Whether it inherits from parent set values or not */
inherits: false;
/* The type. Yes, the type. You thought TypeScript was cool */
syntax: '<angle>';
}
@keyframes spin {
to {
--spinAngle: 360deg;
}
}
The declared type does two jobs: it validates the value (giving you something like a mini spec for your own property), and it tells the browser how to animate. A property can be typed as any of the following:
lengthnumberpercentagelength-percentagecolorimageurlintegerangletimeresolutiontransform-listtransform-functioncustom-ident
Previously, getting animations out of custom properties usually meant reaching for workarounds. One common pattern scoped a handful of variables to a set of elements and drove several different animations from a single keyframe definition through :nth-child() scoping.
Animating color
Color is a good place to start because HSL breaks a color into numbers you can reason about: hue, saturation and lightness. Because a hue is numeric, it can be animated directly.
Take a rainbow built from bands, each scoped with :nth-child() and each carrying an --index for sizing. One version animates the bands by giving each a negative animation-duration delay and cycling only through a small number of keyframe steps. That produces a stepped jump effect, and the step values (a rough 14% in the original) aren't especially accurate.
Animating border-color would also get the job done, at the cost of two problems: the same keyframe step calculation, plus a lot of extra CSS. Both go away once --hue is registered as a number:
@property --hue {
initial-value: 0;
inherits: false;
syntax: '<number>';
}
HSL hues run from 0 to 360, so the property starts at 0, doesn't inherit, and is typed as a number. The animation then becomes straightforward:
@keyframes rainbow {
to {
--hue: 360;
}
}
Each band's starting point is set with a delay, which gives flexible control — change animation-duration and the whole wheel slows down.
Before @property, animating through the color wheel required generated keyframes, for instance from a preprocessor like Stylus:
@keyframes party
for $frame in (0..100)
{$frame * 1%}
background 'hsl(%s, 65%, 40%)' % ($frame * 3.6)
The generation is necessary only because the browser doesn't understand the intent: going from a hue of 0 to 360 looks like no change at all, since both hsl values render as the same color, so the browser treats the transition as instant. Because the keyframes are identical, it assumes the background stays put instead of sweeping the spectrum and returning to where it began.
Beyond hue, there's room to animate saturation or lightness, try rgb(), or use degrees in hsl() and declare the property as <angle>. Values can also be shared across elements through scoping — a button whose border and shadow travel around the color wheel on hover, for example.
Counting with numbers
integer and number types let you animate a number for its own sake. Combined with CSS counters, an animated integer can be converted to a string through counter and a pseudo-element, then used as that pseudo-element's content:
@property --milliseconds {
inherits: false;
initial-value: 0;
syntax: '<integer>';
}
.counter {
counter-reset: ms var(--milliseconds);
animation: count 1s steps(100) infinite;
}
.counter:after {
content: counter(ms);
}
@keyframes count {
to {
--milliseconds: 100;
}
}
Push that a bit further and you have a stopwatch built from nothing but HTML and CSS — buttons included, and it genuinely functions as a timer. It doesn't drift the way setInterval-based timers can, which in some respects makes it more accurate than the JavaScript solutions commonly reached for (Google Chrome Developers covers JavaScript counters in a video on the topic). Countdowns are an obvious next use.
Gradients: color stops and angles
Want to transition the color stops of a linear, radial or conic gradient? Registering a typed property makes that possible.
The beach-waves example layers several images. Each color stop is built with calc(), and the value of --wave is added into that calculation — so animating --wave alone moves every wave layer at once:
body {
animation: waves 5s infinite ease-in-out;
}
@keyframes waves {
50% {
--wave: 25%;
}
}
Without @property the waves would jump between high and low tide; with it, the motion is smooth. Related techniques include rotating an image, or animating the angle of a conic-gradient inside a border-image (Bramus Van Damme covers the concept in detail).
A charging indicator shows both at once: animate an angle and a hue together, using two custom properties:
@property --angle {
initial-value: 0deg;
inherits: false;
syntax: '<number>';
}
@property --hue {
initial-value: 0;
inherits: false;
syntax: '<angle>';
}
The animation moves the angle and hue with a slight pause on each iteration, and the result is applied to the element as a border-image:
@keyframes load {
0%, 10% {
--angle: 0deg;
--hue: 0;
}
100% {
--angle: 360deg;
--hue: 100;
}
}
.loader {
--charge: hsl(var(--hue), 80%, 50%);
border-image: conic-gradient(var(--charge) var(--angle), transparent calc(var(--angle) * 0.5deg)) 30;
animation: load 2s infinite ease-in-out;
}
border-image doesn't cooperate with border-radius, but a pseudo-element placed behind the element works as a substitute. Pair that with the number-animation trick above and you get a full charging/loading animation that changes its appearance once it hits 100%.
Composing transforms
Transitions between transform values have a well-known failure mode: the intermediate states break or don't look right. Throwing a ball from point A to B under the effect of gravity is the classic case.
A naive attempt already exists as an animated transform, but it doesn't look anything like a throw. Wrapper elements animated separately used to be the workaround. With @property, the individual values inside a transform can be animated together on one timeline. Start by defining custom properties and setting the ball's transform from them:
@property --x {
inherits: false;
initial-value: 0%;
syntax: '<percentage>';
}
@property --y {
inherits: false;
initial-value: 0%;
syntax: '<percentage>';
}
@property --rotate {
inherits: false;
initial-value: 0deg;
syntax: '<angle>';
}
.ball {
animation: throw 1s infinite alternate ease-in-out;
transform: translateX(var(--x)) translateY(var(--y)) rotate(var(--rotate));
}
Then compose the desired transform against the keyframes in the animation:
@keyframes throw {
0% {
--x: -500%;
--rotate: 0deg;
}
50% {
--y: -250%;
}
100% {
--x: 500%;
--rotate: 360deg;
}
}
That yields the curved path, and its character changes with the timing function chosen — splitting the animation into three segments with different timing functions gives three different styles of movement.
A car driving around a square with rounded corners uses the same approach: its transform is calculated with vmin to stay responsive, and the journey can be scripted frame by frame, beginning with --x. Adding the y-axis travel alone isn't quite right, so extra steps go into @keyframes to smooth the path. The last piece is rotation at the corners, using a 5% window — not precise, but enough to demonstrate the potential. The result needs no wrappers and no complex math, just composed custom properties.
Whole scenes from a few variables
Taken together, these techniques can power an entire scene with a small number of registered properties. A 404 page concept, for instance, has its moving parts driven by two of them: a moving gradient clipped with -webkit-background-clip, a shadow that reads the property values, and another element that swings to create a light effect.
Where the types could go next
Giving the browser better information about a custom property opens up the same range of tricks the numbers-as-strings era ruled out. Speculating on the remaining types: time and resolution would make interesting transitions (though getting them to behave didn't pan out here), and url could allow transitioning between a range of sources, the way an image carousel works.



