Règle CSSRègles @

@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é.

Sur cette page

Exemple

#
CSS
@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; }
}
Aperçu

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

#
Syntaxe
@property --nom {
  syntax: "<type>";
  inherits: true | false;
  initial-value: <valeur>;
}

Descripteurs et types

#
  • syntax: "<percentage>"

    la barre se remplit en douceur

    La variable --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.
  • sans @property

    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.
  • syntax: "<angle>"

    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.
  • syntax: "<integer>"

    un compteur de 0 à 100

    Un entier transmis à un compteur CSS (counter-reset) et affiché via content. L’animation compte en douceur de 0 à 100.
  • syntax: "<color>"

    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.
  • inherits: false

    l’enfant n’hérite pas

    Le parent définit --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.
  • initial-value

    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>"

La variable --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

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.
.bar {
  animation: fill 2s infinite alternate;
}
@keyframes fill { to { --p: 100%; } }

syntax: "<angle>"

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.
@property --angle {
  syntax: "<angle>";
  inherits: false;
  initial-value: 0deg;
}

.ring {
  animation: turn 2.5s linear infinite;
}
@keyframes turn { to { --angle: 360deg; } }

syntax: "<integer>"

Un entier transmis à un compteur CSS (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>"

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.
@property --c {
  syntax: "<color>";
  inherits: false;
  initial-value: #7c3aed;
}

.swatch {
  animation: tint 2s infinite alternate;
}
@keyframes tint { to { --c: #f59e0b; } }

inherits: false

Le parent définit --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

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.
@property --radius {
  syntax: "<length>";
  inherits: false;
  initial-value: 24px;
}

.tile { border-radius: var(--radius); }

Plus d’exemples

#
Un bouton qui se remplit au survol
CSS
@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%;
}
Aperçu

Survolez le bouton. Une variable enregistrée peut aussi être animée par une transition ordinaire, et pas seulement par une animation @keyframes.

Enregistrement depuis JavaScript
JavaScript
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 @property modifiera la variable d’un coup, mais le dégradé s’affichera quand même.

Entrées associées

#

Pratiquer dans les leçons

#

Vous voyez une erreur ou il manque un exemple ? Écrivez-nous.