The Times You Need A Custom @property Instead Of A CSS Variable

We generally use a CSS variable as a placeholder for some value we plan to reuse — to avoid repeating the same value and to easily update that value across the board if it needs to be updated.

:root { 
  --mix: color-mix(in srgb, #8A9B0F, #fff 25%);
}

div {
  box-shadow: 0 0 15px 25px var(--mix);
}

We can register custom properties in CSS using @property. The most common example you’ll likely find demonstrates how @property can animate the colors of a gradient, something we’re unable to do otherwise since a CSS variable is recognized as a string and what we need is a number format that can interpolate between two numeric values. That’s where @property allows us to define not only the variable’s value but its syntax, initial value, and inheritance, just like you’ll find documented in CSS specifications.

For example, here’s how we register a custom property called --circleSize, which is formatted as a percentage value that is set to 10% by default and is not inherited by child elements.

@property --circleSize {
  syntax: "<percentage>";
  inherits: false;
  initial-value: 10%;
}

div { /* red div */
  clip-path: circle(var(--circleSize) at center bottom);
  transition: --circleSize 300ms linear;
}

section:hover div { 
  --circleSize: 125%; 
}

In this example, a circle() function is used to clip the <div> element into — you guessed it — a circle. The size value of the circle()’s radius is set to the registered custom property, --circleSize, which is then independently changed on hover using a transition. The result is something close to Material Design’s ripple effect, and we can do it because we’ve told CSS to treat the custom property as a percentage value rather than a string:

See the Pen CSS @property [forked] by Preethi Sam.

The freedom to define and spec our own CSS properties gives us new animating superpowers that were once only possible with JavaScript, like transitioning the colors of a gradient.

Here’s an idea I have that uses the same basic idea as the ripple, only it chains multiple custom properties together that are formatted as colors, lengths, and angle degrees for a more complex animation where text slides up the container as the text changes colors.

See the Pen Text animation with @property [forked] by Preethi Sam.

Let’s use this demo as an exercise to learn more about defining custom properties with the @property at-rule, combining what we just saw in the ripple with the concept of interpolating gradient values.

The HTML

<div class="scrolling-text">
  <div class="text-container">
    <div class="text">
      <ruby>壹<rt>one</rt></ruby>
      <ruby>蜀<rt>two</rt></ruby>
      <ruby>兩<rt>three</rt></ruby>
    </div>
  </div>
</div>

The HTML contains Chinese characters we’re going to animate. These Chinese characters are marked up with <ruby> tags so that their English translations can be supplied in <rt> tags. The idea is that .scrolling-text is the component’s parent container and, in it, is a child element holding the sliding text characters that allow the characters to slide in and out of view.

Vertical Sliding

In CSS, let’s make the characters slide vertically on hover. What we’re making is a container with a fixed height we can use to clip the characters out of view when they overflow the available space.

.scrolling-text {
  height: 1lh;
  overflow: hidden;
  width: min-content;
}
.text-container:has(:hover, :focus) .text {
  transform: translateY(-2lh) ;
}
.text {
  transition: transform 2.4s ease-in-out;
}

See the Pen Vertical text transition [forked] by Preethi Sam.

Setting the .scrolling-text container’s width to min-content gives the characters a tight fit, stacking them vertically in a single column. The container’s height is set 1lh. And since we’ve set overflow: hidden on the container, only one character is shown in the container at any given point in time.

Tip: You can also use the HTML <pre> element or either the white-space or text-wrap properties to control how text wraps.

On hover, the text moves -2lh, or double the height of a single text character in the opposite, or up, direction. So, basically, we’re sliding things up by two characters in order to animate from the first character to the third character when the container holding the text is in a hovered state.

Applying Gradients To Text

Here’s a fun bit of styling:

.text {
  background: repeating-linear-gradient(
    180deg, 
    rgb(224, 236, 236), 
    rgb(224, 236, 236) 5px, 
    rgb(92, 198, 162) 5px, 
    rgb(92, 198, 162) 6px);
  background-clip: text;
  color: transparent; /* to show the background underneath */
  background-size: 20% 20%;
}

How often do you find yourself using repeating gradients in your work? The fun part, though, is what comes after it. See, we’re setting a transparent color on the text and that allows the repeating-linear-gradient() to show through it. But since text is a box like everything else in CSS, we clip the background at the text itself to make it look like the text is cut out of the gradient.

See the Pen A gradient text (Note: View in Safari or Chrome) [forked] by Preethi Sam.

Pretty neat, right? Now, it looks like our text characters have a striped pattern painted on them.

Animating The Gradient

This is where we take the same animated gradient concept covered in other tutorials and work it into what we’re doing here. For that, we’ll first register some of the repeating-linear-gradient() values as custom properties. But unlike the other implementations, ours is a bit more complex because we will animate several values rather than, say, updating the hue.

Instead, we’re animating two colors, a length, and an angle.

@property --c1 {
  syntax: "<color>";
  inherits: false;
  initial-value: rgb(224, 236, 236);
}
@property --c2 {
  syntax: "<color>";
  inherits: false;
  initial-value: rgb(92, 198, 162);
}
@property --l {
  syntax: "<length> | <percentage>";
  inherits: false;
  initial-value: 5px;
}
@property --angle {
  syntax: "<angle>";
  inherits: false;
  initial-value: 180deg;
}

.text {
  background: repeating-linear-gradient(
    var(--angle), 
    var(--c1), 
    var(--c1) 5px, 
    var(--c2) var(--l), 
    var(--c2) 6px);
}

We want to update the values of our registered custom properties when the container that holds the text is hovered or in focus. All that takes is re-declaring the properties with the updated values.

.text-container:has(:hover, :focus) .text {
  --c1: pink;
  --c2: transparent;  
  --l: 100%;
  --angle: 90deg;

  background-size: 50% 100%;
  transform:  translateY(-2lh);
}

To be super clear about what’s happening, these are the custom properties and values that update on hover:

--c1: Starts with a color value of rgb(224, 236, 236) and updates to pink.
--c2: Starts with a color value of rgb(92, 198, 162) and updates to transparent.
--l: Starts with length value 5px and updates to 100%.
--a: Starts with an angle value of 180deg and updates to 90deg.

So, the two colors used in the gradient transition into other colors while the overall size of the gradient increases and rotates. It’s as though we’re choreographing a short dance routine for the gradient.

Refining The Transition

All the while, the .text element containing the characters slides up to reveal one character at a time. The only thing is that we have to tell CSS what will transition on hover, which we do directly on the .text element:

.text {
  transition: --l, --angle, --c1, --c2, background-size, transform 2.4s ease-in-out;
  transition-duration: 2s; 
}

Yes, I could just as easily have used the all keyword to select all of the transitioning properties. But I prefer taking the extra step of declaring each one individually. It’s a little habit to keep the browser from having to watch for too many things, which could slow things down even a smidge.

Final Demo

Here’s the final outcome once again:

See the Pen Text animation with @property [forked] by Preethi Sam.

I hope this little exercise not only demonstrates the sorts of fancy things we can make with CSS custom properties but also helps clarify the differences between custom properties and standard variables. Standard variables are excellent placeholders for more maintainable code (and a few fancy tricks of their own) but when you find yourself needing to update one value in a property that supports multiple values — such as colors in a gradient — the @property at-rule is where it’s at because it lets us define variables with a custom specification that sets the variable’s syntax, initial value, and inheritance behavior.

When we get to amend values individually and independently with a promise of animation, it both helps streamline the code and opens up new possibilities for designing elaborate animations with relatively nimble code.

That’s why @property is a useful CSS standard to keep in mind and keep ready to use when you are thinking about animations that involve isolated value changes.