@property

Baseline 2024

Newly available

Since July 2024, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

Expérimental: Cette fonction est expérimentale
Puisque cette fonction est toujours en développement dans certains navigateurs, veuillez consulter le tableau de compatibilité pour les préfixes à utiliser selon les navigateurs.
Il convient de noter qu'une fonctionnalité expérimentale peut voir sa syntaxe ou son comportement modifié dans le futur en fonction des évolutions de la spécification.

La règle at-rule CSS @property fait partie du panel d'API CSS Houdini, qui permet aux développeuses et développeurs de définir explicitement leurs propriétés CSS personnalisées (voir CSS custom properties). Cela permet la vérification des types de propriétés, de leur donner des valeurs par défaut et de déterminer si une propriété peut hériter ses valeurs ou non.

La règle @property permet l'enregistrement d'une propriété personnalisée directement dans une feuille de styles sans avoir à utiliser la moindre ligne de JavaScript. Une règle @property valide enregistre une nouvelle propriété personnalisée comme si CSS.registerProperty avait été appelé avec les mêmes paramètres.

Syntaxe

css
@property --property-name {
  syntax: "<color>";
  inherits: false;
  initial-value: #c0ffee;
}

Descripteurs

syntax

Décrit la syntaxe autorisée de la propriété.

inherits

Détermine si l'enregistrement de la propriété personnalisée spécifiée avec @property hérite ou non par défaut.

initial-value

Détermine la valeur initiale de la propriété.

Une règle @property valide enregistre une propriété personnalisée avec comme nom de propriété la sérialisation du préfixe de la règle.

Une règle @property nécessite le respect d'une syntaxe (voir syntax) et une description d'héritage (voir inherits). Si l'un des deux manque, l'ensemble de la règle est invalide et celle-ci doit être ignorée. Le descripteur initial-value est optionnel, uniquement si la syntaxe est une définition de syntaxe universelle. Sinon, le descripteur est requis (s'il manque, l'ensemble de la règle est invalide et celle-ci doit être ignorée).

Les descripteurs inconnus ne sont pas valides et sont ignorés, mais n'invalident pas l'ensemble de la règle @property.

Exemples

Ajout d'une vérification de type à la propriété personnalisée --my-color en tant que couleur avec une valeur par défaut, sans lui permettre d'hériter de sa valeur :

Utilisation de la règle CSS at-rule @property :

css
@property --my-color {
  syntax: "<color>";
  inherits: false;
  initial-value: #c0ffee;
}

Équivalent avec la fonction JavaScript CSS.registerProperty :

js
window.CSS.registerProperty({
  name: "--my-color",
  syntax: "<color>",
  inherits: false,
  initialValue: "#c0ffee",
});

Syntaxe formelle

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

Spécifications

Specification
CSS Properties and Values API Level 1
# at-property-rule

Compatibilité des navigateurs

BCD tables only load in the browser

Voir aussi