Leveraging CSS @property (Houdini) for Advanced Animations and Custom Property Control

The CSS @property at‑rule, part of the CSS Houdini API, lets developers explicitly declare custom properties with a type ( syntax ), a default value ( initial-value ) and inheritance behavior ( inherits ), enabling type‑checked variables that can be animated.

Typical custom property usage is shown first, followed by the Houdini version where a property is defined with @property --property-name { syntax: ' '; inherits: false; initial-value: #fff; } and then referenced via var(--property-name) .

A concise list of supported syntax types is provided, including color , length , percentage , angle , image , url , integer , resolution , transform-list , and custom identifiers.

Special symbols in syntax definitions ( + , # , | ) are explained, showing how to accept space‑separated lists, comma‑separated lists, or alternative types.

Gradient Background Animation with color Syntax

By defining two Houdini properties ( --houdini-colorA and --houdini-colorB ) with syntax: '<color>' , a linear‑gradient background can be smoothly transitioned using transition: 1s --houdini-colorA, 1s --houdini-colorB instead of the non‑animatable background property.

@property --houdini-colorA { syntax: '<color>'; inherits: false; initial-value: #fff; }
@property --houdini-colorB { syntax: '<color>'; inherits: false; initial-value: #000; }
.property { background: linear-gradient(45deg, var(--houdini-colorA), var(--houdini-colorB)); transition: 1s --houdini-colorA, 1s --houdini-colorB; }

Conic‑Gradient Pie‑Chart Animation with percentage Syntax

A custom property --per of type percentage drives the stop point of a conic-gradient , allowing a smooth hover animation via transition: --per 300ms linear .

@property --per { syntax: '<percentage>'; inherits: false; initial-value: 25%; }
div { background: conic-gradient(yellowgreen, yellowgreen var(--per), transparent var(--per), transparent 100%); transition: --per 300ms linear; &:hover { --per: 60%; } }

Length‑Based Underline Transition

Using a length typed property ( --offset ) enables a smooth transition of text-underline-offset and colour on hover.

@property --offset { syntax: '<length>'; inherits: false; initial-value: 0; }
div { text-underline-offset: var(--offset, 1px); text-decoration: underline; transition: --offset 400ms, text-decoration-color 400ms; &:hover { --offset: 10px; color: orange; text-decoration-color: orange; } }

Screen‑Saver Animation with Multiple Percentage and Angle Properties

Several @property definitions ( --perA – --perE and --angle ) are animated via a @keyframes move rule, driving radial‑gradient positions and a rotating linear gradient to create a dynamic background.

@property --perA { syntax: '<percentage>'; inherits: false; initial-value: 75%; }
/* similar definitions for --perB, --perC, --perD, --perE, --angle */
body { background-image: radial-gradient(circle at var(--perE) 7%, rgba(40,40,40,0.04) 0%, rgba(40,40,40,0.04) 50%, rgba(200,200,200,0.04) 50%, rgba(200,200,200,0.04) 100%),
                 radial-gradient(circle at var(--perC) var(--perD), rgba(99,99,99,0.04) 0%, rgba(99,99,99,0.04) 50%, rgba(45,45,45,0.04) 50%, rgba(45,45,45,0.04) 100%),
                 radial-gradient(circle at var(--perA) var(--perB), rgba(243,243,243,0.04) 0%, rgba(243,243,243,0.04) 50%, rgba(37,37,37,0.04) 50%, rgba(37,37,37,0.04) 100%),
                 linear-gradient(var(--angle), rgb(34,222,237), rgb(135,89,215));
          animation: move 30s infinite alternate linear; }
@keyframes move { 100% { --perA:85%; --perB:49%; --perC:45%; --perD:39%; --perE:70%; --angle:360deg; } }

The article concludes with references to MDN, the CSS Properties and Values API Level 1 spec, and several CodePen demos that illustrate each technique.