@property

Syntaxe

@property --rotation {
  syntax: "<angle>";
  inherits: false;
  initial-value: 45deg;
}

Le nom de la propriété personnalisée est un <dashed-ident> qui commence par -- et est suivi d'un identifiant valide défini par l'utilisateur·ice. Il est sensible à la casse.

Descripteurs

Les conditions suivantes doivent être respectées pour que la règle @property soit valide :

• La règle @property doit inclure les descripteurs syntax et inherits. Si l'un des deux manque, la règle entière est invalide et ignorée.
• Le descripteur initial-value est optionnel si la valeur du descripteur syntax est la définition universelle (syntax: "*"). Si le descripteur initial-value est requis mais omis, la règle entière est invalide et ignorée.
• Si la valeur du descripteur syntax n'est pas la définition universelle, le descripteur initial-value doit être une valeur indépendante du calcul^(angl.). Cela signifie que la valeur peut être convertie en valeur calculée sans dépendre d'autres valeurs, sauf pour les définitions « globales » indépendantes de CSS. Par exemple, 10px est indépendant du calcul : il ne change pas lors de la conversion en valeur calculée. 2in est aussi valide, car 1in équivaut toujours à 96px. En revanche, 3em n'est pas valide, car la valeur d'un em dépend de la propriété font-size du parent.
• Les descripteurs inconnus sont invalides et ignorés, mais n'invalident pas la règle @property.

Syntaxe formelle

@property = 
  @property <custom-property-name> { <declaration-list> }  

Exemples

Utiliser @property pour enregistrer et utiliser une propriété personnalisée

Dans cet exemple, on définit deux propriétés personnalisées, --item-size et --item-color, qui serviront à définir la taille (largeur et hauteur) et la couleur d'arrière-plan des trois éléments suivants.

<div class="container">
  <div class="item one">Élément un</div>
  <div class="item two">Élément deux</div>
  <div class="item three">Élément trois</div>
</div>

Le code suivant utilise la règle CSS @property pour définir une propriété personnalisée nommée --item-size. La propriété définit la valeur initiale à 40% et limite les valeurs valides aux valeurs de type <percentage> uniquement. Cela signifie que, lorsqu'elle est utilisée pour la taille d'un élément, sa taille sera toujours relative à celle de son parent. La propriété est héritée.

@property --item-size {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 40%;
}

On définit une seconde propriété personnalisée, --item-color, en utilisant JavaScript au lieu de CSS. La méthode JavaScript registerProperty() est équivalente à la règle @property. La propriété est définie avec une valeur initiale aqua, n'accepte que des valeurs de type <color>, et n'est pas héritée.

window.CSS.registerProperty({
  name: "--item-color",
  syntax: "<color>",
  inherits: false,
  initialValue: "aqua",
});

On utilise les deux propriétés personnalisées pour mettre en forme les éléments :

.container {
  display: flex;
  height: 200px;
  border: 1px dashed black;

  /* valeurs des propriétés personnalisées sur le parent */
  --item-size: 20%;
  --item-color: orange;
}

/* utilisation des propriétés personnalisées pour la taille et la couleur d'arrière-plan */
.item {
  width: var(--item-size);
  height: var(--item-size);
  background-color: var(--item-color);
}

/* valeurs des propriétés personnalisées sur l'élément lui-même */
.two {
  --item-size: initial;
  --item-color: inherit;
}

.three {
  /* valeurs invalides */
  --item-size: 1000px;
  --item-color: xyz;
}

Les deux propriétés personnalisées, --item-size: 20% et --item-color: orange;, sont définies sur le parent container, ce qui remplace les valeurs par défaut 40% et aqua définies lors de la création de ces propriétés. La taille est héritée, la couleur ne l'est pas.

Pour l'élément un, aucune de ces propriétés personnalisées n'a été définie. La propriété --item-size est héritée, donc la valeur 20% définie sur le parent container est utilisée. En revanche, la propriété --item-color n'est pas héritée, donc la valeur orange du parent n'est pas prise en compte. À la place, la valeur initiale par défaut aqua est utilisée.

Pour l'élément deux, des mots-clés globaux CSS sont définis pour les deux propriétés personnalisées, ce qui sont des valeurs valides pour tous les types et donc valides quel que soit le descripteur syntax. La propriété --item-size est définie sur initial et utilise la valeur initial-value: 40%; définie dans la déclaration @property. La valeur initial signifie que la valeur initialValue de la propriété est utilisée. La propriété --item-color est définie sur inherit, héritant explicitement la valeur orange du parent même si la propriété personnalisée n'est pas censée être héritée. C'est pourquoi l'élément deux est orange.

Pour l'élément trois, la valeur de --item-size est définie sur 1000px. Bien que 1000px soit une valeur de type <length>, la déclaration @property exige une valeur de type <percentage>, donc la déclaration est invalide et ignorée, ce qui fait que la valeur héritée 20% du parent est utilisée. La valeur xyz est également invalide. Comme registerProperty() a défini --item-color comme non héritée, la valeur initiale par défaut aqua est utilisée et non la valeur orange du parent.

Animer la valeur d'une propriété personnalisée

Dans cet exemple, on définit une propriété personnalisée appelée --progress avec @property : elle accepte des valeurs de type <percentage> et a une valeur initiale de 25%. On utilise --progress pour définir la position des arrêts de couleur dans un linear-gradient(), spécifiant où le vert s'arrête et où le noir commence. On anime ensuite la valeur de --progress jusqu'à 100% sur 2,5 secondes, ce qui donne l'effet d'une barre de progression animée.

<div class="bar"></div>

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

.bar {
  display: inline-block;
  --progress: 25%;
  width: 100%;
  height: 5px;
  background: linear-gradient(
    to right,
    #00d230 var(--progress),
    black var(--progress)
  );
  animation: progressAnimation 2.5s ease infinite;
}

@keyframes progressAnimation {
  to {
    --progress: 100%;
  }
}

Spécifications

Compatibilité des navigateurs

Voir aussi

• var()
• API Propriétés et valeurs CSS
• API Peinture CSS
• API Typage de modèle d'objet CSS
• CSS Houdini
• Guide d'utilisation des propriétés CSS personnalisées (variables)
• Module des propriétés CSS personnalisées pour les variables en cascade