radial-gradient

La fonction radial-gradient() permet de créer une <image> CSS représentant un dégradé de couleur. Ce dégradé diffuse depuis une origine, le centre du gradient. La valeur renvoyée par cette fonction est un objet CSS de type <gradient>.

Les dégradés radiaux sont définis par trois notions :

• Le centre,
• La forme de terminaison : le contour et sa position,
• Les points de couleur (color stops).

Pour obtenir un dégradé radial, on trace des formes uniformes concentriques, identiques à la formes de terminaison en partant du centre. Les points de couleur sont positionnés sur un rayon virtuel qui s'étend horizontalement depuis le centre et vers la droite. Lorsqu'on positionne ces points avec des pourcentages, la valeur sera relative au rayon total qui est la distance entre le centre et la forme de terminaison. Chaque forme a une seule couleur qui est déterminée par la couleur du point d'intersection entre le rayon et la forme.

Les formes de terminaisons peuvent prendre deux formes :

• circulaire (avec le mot-clé circle)
• elliptique (avec le mot-clé ellipse).

De façon analogue aux autres types de dégradés, un dégradé radial n'est pas une couleur (<color>) CSS mais une image sans dimension intrinsèque (c'est-à-dire que celle-ci ne possède pas de taille naturelle ou préférée ni de proportion). Sa taille réelle correspondra à la taille de l'élément auquel le gradient s'applique.

La fonction radial-gradient ne permet pas d'obtenir des dégradés radiaux répétés. Pour obtenir un tel effet concentrique, on pourra utiliser la fonction CSS repeating-radial-gradient.

Syntaxe

/* On définit la forme de terminaison */
radial-gradient( circle, … )
radial-gradient( ellipse, … )
radial-gradient( <extent-keyword>, … )

/* Un cercle centré d'un rayon indiqué (absolu) */ 
radial-gradient( circle radius, … ) 

/* Les deux demi-axes d'une ellipse, horizontal, puis vertical */ 
radial-gradient( ellipse x-axis y-axis, … )

/* On définit la position de la forme */
radial-gradient (… at <position>, … )

/* On définit les points de couleur */
radial-gradient (…, <color-stop>)
radial-gradient (…, <color-stop>, <color-stop>)

Valeurs

<position>

Une <position> CSS qui est interprétée de la même façon que pour les propriétés background-position ou transform-origin. La valeur par défaut est center.

<shape>

La forme du gradient. Elle vaut soit circle (la forme du dégradé sera un cercle de rayon constant) ou ellipse (la forme est une ellipse alignée sur les axes). La valeur par défaut est ellipse.

<color-stop>

Ces valeurs indiquent qu'une couleur donnée doit être utilisée à un endroit spécifique du dégradé. Cette valeur se compose d'une valeur <color> éventuellement suivie d'une position définie par une pourcentage (<percentage>) ou une longueur (<length>) selon le rayon virtuel du gradient. Un pourcentage ou une longueur nulle (0% ou 0) indiquera le centre du dégradé. La valeur 100% correspondra à l'intersection entre la forme de terminaison et le rayon virtuel. Les valeurs intermédiaires seront situées de façon proportionnelle.

<extent-keyword>

Des mots-clés qui permettent de décrire la taille de la forme de terminaison. Les valeurs possibles sont :

Constante	Description
closest-side	La forme de terminaison du dégradé touche le côté de la boîte le plus proche du centre (pour les cercles) ou touche les côtés horizontaux et verticaux les plus proches du centre (pour les ellipses).
closest-corner	La forme de terminaison du dégradé est dimensionnée afin de toucher exactement le coin de la boîte le plus proche du centre.
farthest-side	Cette valeur fonctionne de façon semblable à closest-side, sauf que ce seront les côtés les plus éloignés qui seront utilisés.
farthest-corner	Cette valeur fonctionne de façon semblable à closest-corner, sauf que ce sera le coin le plus éloigné qui sera utilisé.

D'anciens brouillons de la spécification indiquaient d'autres mots-clés, cover et contain, respectivement synonymes des valeurs standards farthest-corner et closest-side. Seules les valeurs standards doivent être utilisées, certaines implémentations ont d'ailleurs déjà retirées les anciennes formes.

Syntaxe formelle

radial-gradient(   [ circle || <length> ] [ at <position> ]? ,
                 | [ ellipse || [ <length>  |  <percentage>  ]{2}] [ at  <position>  ]? ,
                 | [ [ circle | ellipse ] || <extent-keyword> ] [ at  <position>  ]? ,
                 | at  <position>  ,
                 <color-stop> [ , <color-stop> ]+ )
avec <extent-keyword> = closest-corner | closest-side | farthest-corner | farthest-side
  et <color-stop> = <color> [ <percentage> | <length> ]?

Exemples

Une ellipse avec farthest-corner

CSS

.exemple {
  height: 100vh;
  width: 200vh;
  background-image: radial-gradient(ellipse farthest-corner at 45px 45px , #00FFFF 0%, rgba(0, 0, 255, 0) 50%, #0000FF 95%);
}

HTML

<p class="exemple">
  Yop
</p>

Résultat

Un cercle de 16 pixels

CSS

.exemple {
  height: 100vh;
  width: 100vh;
  background-image: radial-gradient(16px at 60px 50% , #000000 0%, #000000 14px, rgba(0, 0, 0, 0.3) 18px, rgba(0, 0, 0, 0) 19px);
}

HTML

<p class="exemple">
  Yop
</p>

Résultat

Spécifications

Compatibilité des navigateurs

[1] Firefox 3.6 implémentait une version préfixée basée sur une ancienne spécification. Avant Firefox 36, Gecko n'appliquait pas de dégradé sur les espaces de couleurs pré-multipliées (pre-multiplied color space) ce qui entraînait l' leading to shade of grey unexpectedly appearing when used with transparency. Since Firefox 42, the prefixed version of gradients can be disabled by setting layout.css.prefixes.gradients to false.

[2] Webkit implémentait auparavant une syntaxe préfixée, basée sur une ancienne spécification. Depuis la version 528, WebKit prend en charge une ancienne fonction -webkit-gradient(radial,…). Voir la prise en charge actuelle de Webkit pour les dégradés radiaux.

[3] Pour les versions d'Internet Explorer entre 5.5 et 9.0, cela pouvait être obtenu avec le filtre propriétaire filter: progid:DXImageTransform.Microsoft.Gradient().

[4] En plus de la version non-préfixée, Gecko 44.0 ((Firefox 44.0 / Thunderbird 44.0 / SeaMonkey 2.41)) a ajouté la prise en charge d'une version préfixée avec -webkit pour des raisons de compatibilité web via la préférence layout.css.prefixes.webkit qui valait false par défaut. Depuis Gecko 49.0 ((Firefox 49.0 / Thunderbird 49.0 / SeaMonkey 2.46)), la préférence est activée par défaut.

Voir aussi

• Manipuler les dégradés CSS,
• repeating-radial-gradient,
• linear-gradient
• La proposition originelle de WebKit
• La nouvelle implémentation de WebKit