@property
Enregistre une variable CSS avec un type, une valeur initiale et une règle d’héritage. Une telle variable peut être animée en douceur, par ex. l’angle d’un dégradé.
Exemple
#@property --angle {
syntax: "<angle>";
inherits: false;
initial-value: 0deg;
}
.card {
border: 3px solid transparent;
border-radius: 14px;
background:
linear-gradient(#18181b, #18181b) padding-box,
conic-gradient(from var(--angle), #7c3aed, #0ea5e9, #10b981, #7c3aed) border-box;
animation: spin 4s linear infinite;
}
@keyframes spin {
to { --angle: 360deg; }
}<div class="card" style="padding: 16px 18px;">
<strong>Compte Premium</strong>
<p style="margin: 4px 0 0; color: #a1a1aa;">Tous les mondes débloqués, sans limite de carburant.</p>
</div>Définition et utilisation
#Une variable CSS ordinaire (--nom) n’est pour le navigateur qu’une chaîne de caractères. Le navigateur ne sait pas que --angle: 45deg est un angle, il ne peut donc pas calculer de valeurs intermédiaires et la modifie d’un coup lors d’une animation. La règle @property enregistre une variable avec un type précis, et le navigateur la traite alors comme une vraie propriété.
L’enregistrement comporte trois descripteurs. syntax définit le type, par ex. "<angle>", "<color>", "<length>", "<number>", "<integer>" ou "<percentage>", et "*" signifie n’importe quelle valeur. inherits indique si les descendants héritent de la valeur. initial-value est la valeur par défaut, requise pour tous les types sauf "*". Elle doit être indépendante du contexte, elle ne peut donc pas être par ex. 2em. Les descripteurs syntax et inherits sont obligatoires.
Le plus grand avantage, ce sont les animations. Dans la plupart des navigateurs, le passage d’un dégradé à un autre se fait d’un coup, mais on peut animer une variable enregistrée utilisée par le dégradé : l’angle dans conic-gradient(), la position d’une couleur ou la couleur elle-même. Un nombre de type <integer> combiné à un compteur CSS peut même compter en douceur de 0 à 100.
On peut aussi enregistrer une variable depuis JavaScript avec CSS.registerProperty(). Le type sert au passage de garde-fou : une valeur non conforme au type, par ex. un nombre dans une variable de type <color>, est rejetée et la variable prend la valeur initiale ou héritée.
Syntaxe
#@property --nom {
syntax: "<type>";
inherits: true | false;
initial-value: <valeur>;
}Descripteurs et types
#la barre se remplit en douceur
La variable--pdéfinit l’endroit où se termine la couleur verte du dégradé. Grâce à l’enregistrement avec un type pourcentage, la barre se remplit en douceur.la barre saute
La même animation sans enregistrement. Le navigateur ne connaît pas le type de la variable : au lieu de valeurs intermédiaires, il la fait passer de 0 % à 100 % à mi-parcours.un dégradé qui tourne
Une variable contenant un angle pilote le point de départ d’un dégradé conique (from var(--angle)). Animer l’angle de 0 à 360 degrés donne un anneau qui tourne.un compteur de 0 à 100
Un entier transmis à un compteur CSS (counter-reset) et affiché viacontent. L’animation compte en douceur de 0 à 100.une couleur dans un dégradé
On ne peut généralement pas faire passer le dégradé lui-même en douceur, mais une couleur stockée dans une variable enregistrée, si. L’extrémité gauche passe du violet à l’ambre.l’enfant n’hérite pas
Le parent définit--accenten vert et a une bordure verte, mais l’enfant n’hérite pas de cette valeur. Il reçoit la valeur initiale, c’est-à-dire le gris. Une variable ordinaire non enregistrée serait verte chez l’enfant.la valeur quand rien n’est défini
Personne n’a défini la variable--radius, et pourtant elle vaut 24px grâce àinitial-value. Sans enregistrement,var(--radius)n’aurait rien à insérer et l’arrondi disparaîtrait.
Descripteurs et types en pratique
#syntax: "<percentage>"
--p définit l’endroit où se termine la couleur verte du dégradé. Grâce à l’enregistrement avec un type pourcentage, la barre se remplit en douceur.@property --p {
syntax: "<percentage>";
inherits: false;
initial-value: 0%;
}
.bar {
animation: fill 2s infinite alternate;
}
@keyframes fill { to { --p: 100%; } }sans @property
.bar {
animation: fill 2s infinite alternate;
}
@keyframes fill { to { --p: 100%; } }syntax: "<angle>"
from var(--angle)). Animer l’angle de 0 à 360 degrés donne un anneau qui tourne.@property --angle {
syntax: "<angle>";
inherits: false;
initial-value: 0deg;
}
.ring {
animation: turn 2.5s linear infinite;
}
@keyframes turn { to { --angle: 360deg; } }syntax: "<integer>"
counter-reset) et affiché via content. L’animation compte en douceur de 0 à 100.@property --n {
syntax: "<integer>";
inherits: false;
initial-value: 0;
}
.count {
counter-reset: n var(--n);
animation: count 3s infinite alternate;
}
@keyframes count { to { --n: 100; } }syntax: "<color>"
@property --c {
syntax: "<color>";
inherits: false;
initial-value: #7c3aed;
}
.swatch {
animation: tint 2s infinite alternate;
}
@keyframes tint { to { --c: #f59e0b; } }inherits: false
--accent en vert et a une bordure verte, mais l’enfant n’hérite pas de cette valeur. Il reçoit la valeur initiale, c’est-à-dire le gris. Une variable ordinaire non enregistrée serait verte chez l’enfant.@property --accent {
syntax: "<color>";
inherits: false;
initial-value: #52525b;
}
.parent {
--accent: #10b981;
border: 3px solid var(--accent);
}
.child { background: var(--accent); }initial-value
--radius, et pourtant elle vaut 24px grâce à initial-value. Sans enregistrement, var(--radius) n’aurait rien à insérer et l’arrondi disparaîtrait.@property --radius {
syntax: "<length>";
inherits: false;
initial-value: 24px;
}
.tile { border-radius: var(--radius); }Plus d’exemples
#@property --fill {
syntax: "<percentage>";
inherits: false;
initial-value: 0%;
}
.btn {
background: linear-gradient(90deg, #7c3aed var(--fill), #27272a var(--fill));
transition: --fill 0.4s ease-out;
}
.btn:hover {
--fill: 100%;
}<button class="btn" type="button" style="padding: 10px 18px; border: 0; border-radius: 10px; color: #fff; font: 600 15px system-ui, sans-serif; cursor: pointer;">Survolez-moi</button>Survolez le bouton. Une variable enregistrée peut aussi être animée par une transition ordinaire, et pas seulement par une animation @keyframes.
CSS.registerProperty({
name: '--angle',
syntax: '<angle>',
inherits: false,
initialValue: '0deg'
})Cela fonctionne comme la règle @property. C’est utile quand une bibliothèque enregistre les variables ou quand le type dépend de données dans un script.
Compatibilité des navigateurs
#Nouveau dans les navigateurs · depuis 2024
Fonctionne dans les versions actuelles de tous les grands navigateurs. Les anciennes versions peuvent ne pas le prendre en charge.
- Chrome
- Edge
- Firefox
- Safari
Bonnes pratiques
#- N’enregistrez que les variables que vous animez ou auxquelles vous voulez donner un type. Les variables ordinaires contenant les couleurs du thème et les espacements n’ont pas besoin d’enregistrement.
- Enregistrez les variables animées avec
inherits: false. Le navigateur n’a alors pas à recalculer leurs valeurs dans tous les descendants. - Veillez à ce que le résultat reste correct sans l’animation. Un navigateur plus ancien sans prise en charge de
@propertymodifiera la variable d’un coup, mais le dégradé s’affichera quand même.
Entrées associées
#- var()Insère la valeur d’une variable CSS, c’est-à-dire d’une propriété personnalisée notée --nom. Permet aussi de fournir une valeur de repli.
- @keyframesDéfinit les étapes successives d’une animation, appelées images clés.
- conic-gradient()Crée une transition de couleurs autour d’un point, comme l’aiguille d’une horloge. Sert aux graphiques circulaires, cercles chromatiques et bordures tournantes.
- transitionUne propriété raccourcie qui rend les changements de valeurs CSS progressifs plutôt que brusques.
- animationRaccourci qui définit tous les paramètres d’une animation basée sur @keyframes.
Pratiquer dans les leçons
#Vous voyez une erreur ou il manque un exemple ? Écrivez-nous.