@property and Typed Custom Properties
A custom property declared the ordinary way, such as --brand: #006eb6, is just text to the browser. It stores the characters and substitutes them wherever you write var(--brand), but it has no idea that those characters represent a color. That lack of understanding has real consequences: the browser cannot validate the value, cannot give it a meaningful default, and cannot animate it, because it does not know how to find the halfway point between two strings. The @property at-rule fixes all three by letting you register a custom property with an explicit type. This page goes deeper than a passing mention: how registration works, why a type is what unlocks animation, how to choose a syntax grammar, and what the inherits flag changes.
The Anatomy of a Registration
You register a custom property with the @property at-rule followed by the property name, including its leading double hyphen. Inside the block you provide three descriptors, two of which are required.
@property --brand-angle {
syntax: '<angle>';
inherits: false;
initial-value: 0deg;
}
The syntax descriptor declares the type, written as a string. The inherits descriptor controls whether the property passes down to descendant elements, and it is required with no default. The initial-value descriptor supplies the value the property holds before any rule sets it, and it is required for every syntax except the universal one. Once registered, the property behaves like a real typed value everywhere it is used: the browser rejects values that do not match the declared type, falls back to the initial value when a declaration is invalid, and can interpolate between two values during a transition or animation.
Why a Type Unlocks Animation
The headline benefit of registration is animation. To animate a value, the browser has to compute intermediate states between a start and an end, and it can only do that when it understands what the value is. An angle interpolates from 0deg to 360deg by stepping through the degrees between them. A plain unregistered custom property holding the text 0deg has no such behavior, because as far as the browser knows it is an arbitrary string, and there is no defined midpoint between one string and another. The result is that an unregistered property cannot animate at all: it can only ever hold one of the fixed values you assign to it.
This is why effects like a rotating conic gradient were historically impossible with custom properties. You can write a conic gradient whose angle comes from var(--brand-angle), but animating that variable did nothing until the property was registered with an angle type. Registration is the missing piece that tells the browser the value is an angle and therefore interpolatable. The demo later on this page shows exactly this difference.
Choosing a Syntax Grammar
The syntax descriptor accepts a small grammar that describes the shape of the allowed value. For most registrations you reach for one of the single component types, written as a string.
-
'<color>'for any valid color, the type you register to animate between two colors smoothly. -
'<length>'for sizes such as16pxor2rem, and'<percentage>'for percentage values. -
'<length-percentage>'for a value that may be either a length or a percentage, which is common for properties that feed into sizing. -
'<number>'for a bare number with no unit, and'<integer>'for whole numbers only. -
'<angle>'for rotational values such as45degor0.25turn, and'<time>'for durations.
Beyond the single types, the grammar supports three combinators for more specific shapes. A plus sign accepts a space-separated list of the type, so '<length>+' matches one or more lengths in a row. A hash accepts a comma-separated list, so '<color>#' matches a comma list of colors. A vertical bar forms a union of alternatives, so '<color> | <length>' accepts either a color or a length, and you can also list specific keyword identifiers as alternatives such as 'auto | <length>'.
There is also the universal syntax, written as '*', which accepts any value at all. Registering with the universal syntax gives you the inherits control and lets you omit the initial value, but it does not enable animation, because a value that can be anything still has no defined way to interpolate. Reach for a specific type whenever you want validation or animation, and reserve the universal syntax for cases where you only need to control inheritance.
The Inherits Flag
The inherits descriptor decides whether the property cascades to descendant elements the way properties like color do, or stays local to the element that sets it the way padding does. The choice is required because the two behaviors lead to genuinely different designs, and the browser will not guess for you.
Set inherits: true when the value is something a whole subtree should share, such as a theme accent color or a spacing rhythm that components read from a common ancestor. A child that does not set its own value receives the ancestor's value automatically. Set inherits: false when the value is meaningful only to the element it is declared on, such as a per-element animation angle or a local size calculation. A non-inheriting property resets to its initial value on every element that does not explicitly set it, which keeps unrelated components from accidentally picking up a value meant for one place. For the rotating gradient example, you want inherits: false, because each element's angle is its own affair and should not leak into its children.
Registering in CSS or JavaScript
The @property at-rule is the declarative path and the one you will use most. It lives in your stylesheet alongside the rest of your CSS, participates in the cascade, and needs no scripting. There is also an imperative path through CSS.registerProperty(), which takes an object with the same descriptors and registers the property from JavaScript.
CSS.registerProperty({
name: '--brand-angle',
syntax: '<angle>',
inherits: false,
initialValue: '0deg'
});
The two paths produce the same registered property. Prefer the @property at-rule for anything that belongs in your design system, since it keeps the registration next to the styles that use it and applies before the first paint. The JavaScript form is useful when a property must be registered dynamically, for instance when a build tool or a component framework generates the descriptors at runtime. Note that registering the same property twice, once in CSS and once in JavaScript, is an error, so pick one path per property.
Seeing the Difference
The demo below uses a slider to set a gradient angle from 0 to 360 degrees on two swatches at once. The left swatch reads its angle from a registered property, so it accepts every value you drag through and the gradient rotates smoothly. The right swatch stands in for a plain, unregistered property, which the browser cannot interpolate, so it can only ever land on a fixed endpoint and never the angles in between. Drag the slider and watch the two diverge.
When you build your own demonstration for your Teaching Video, the browser developer tools make the typing visible. Inspecting an element and watching the registered property in the computed styles panel shows the value stepping through its intermediate states as it changes, while an unregistered property only ever holds a static string. That stepping is the clearest evidence that registration is what makes the value interpolatable.
Teaching Video Checklist
When you record your teaching video, make sure your teammates come away understanding these concepts:
- Why a plain custom property cannot be animated, demonstrated by showing a value that can only ever land on a fixed endpoint
-
The three descriptors of an
@propertyregistration and what each one does, with special attention to whyinheritsis always required - How registering a type turns a previously static value into an animatable one, shown live with a typed value sweeping smoothly where the untyped one cannot
-
The difference between the declarative
@propertyat-rule and the imperativeCSS.registerProperty(), and when each one is the right choice - Your own demo: a registered custom property driving a value the browser could not animate before, such as a gradient angle, a hue, or a number feeding into another property
Start by inspecting your registered property in the browser developer tools and stepping through the computed style as it changes, so your teammates can see the value moving through its intermediate states. That stepping is the clearest proof that the type is what makes the value interpolatable.
Resources
- MDN: @property covers the at-rule, every descriptor, and the rules around required values
- MDN: CSS.registerProperty() documents the JavaScript registration path and its descriptor object
- web.dev: Smoother and sharper animations with @property walks through animating gradients and other previously static values
- Can I Use: @property shows current browser support data