Fonction CSS `hwb()`

Baseline Large disponibilit *

Cette fonctionnalit est bien tablie et fonctionne sur de nombreux appareils et versions de navigateurs. Elle est disponible sur tous les navigateurs depuis avril 2022.

* Certaines parties de cette fonctionnalit peuvent bnficier de prise en charge variables.

En savoir plus
Voir la compatibilit complte

La fonction CSS hwb() exprime un espace de couleur sRGB donn selon sa teinte, sa blancheur et sa noirceur. Une composante alpha optionnelle reprsente l'opacit de la couleur.

Exemple interactif

background: hwb(12 50% 0%);

background: hwb(50deg 30% 40%);

background: hwb(0.5turn 10% 0% / 0.5);

background: hwb(0 100% 0% / 50%);

<section id="default-example">
  <div class="transition-all" id="example-element"></div>
</section>

#example-element {
  min-width: 100%;
  min-height: 100%;
  padding: 10%;
}

Cette fonction de couleur dans l'espace colorimtrique sRGB est dfinie par une valeur d'angle <hue>, une valeur de blancheur, une valeur de noirceur et, optionnellement, une valeur alpha reprsentant la transparence de la couleur.

Les angles correspondant des teintes particulires diffrent selon les espaces colorimtriques sRGB (utilis par hsl() et hwb()), CIELAB (utilis par lch()) et Oklab (utilis par oklch()). hwb() est dans le mme espace colorimtrique que hsl(), et a donc les mmes angles de teinte. Consultez la page de rfrence <hue> pour plus de dtails et d'exemples, ou essayez de modifier les teintes sur le slecteur de couleur pour voir le rsultat.

Une couleur hwb() est compltement sature lorsque ses valeurs de blancheur (W) et de noirceur (B) sont toutes deux 0. Pour toute valeur de teinte H, hwb(H 0% 0%) correspond la mme couleur que hsl(H 100% 50%). Augmenter la valeur de blancheur claircit la couleur. Augmenter la noirceur assombrit la couleur.

Lorsque la noirceur et la blancheur sont toutes deux suprieures 0, la couleur devient attnue, tendant vers le gris. Lorsque la somme de la blancheur et de la noirceur ajoutes est gale ou suprieure 100% autrement dit, si W + B >= 100%, la fonction de couleur dfinit une nuance de gris. Lorsque la somme des deux valeurs est suprieure 100% (W + B > 100%), les valeurs de blancheur et de noirceur du gris sont effectivement normalises comme W / (W + B) et B / (W + B) respectivement.

Syntaxe

css

/* Valeurs absolues */
hwb(194 0% 0%)
hwb(194 0% 0% / .5)

/* Valeurs relatives */
hwb(from green h w b / 0.5)
hwb(from #123456 h calc(w + 30) b)
hwb(from lch(40% 70 240deg) h w calc(b - 30))

Valeurs

Vous trouverez ci-dessous la description des valeurs autorises pour les couleurs absolues et les couleurs relatives.

Syntaxe des valeurs absolues

hwb(H W B[ / A])

Les paramtres sont les suivants :

H: Un nombre (<number>), un <angle> ou le mot-cl none (quivalent 0deg dans ce cas) reprsentant l'angle de <hue> de la couleur.
W: Un pourcentage (<percentage>) reprsentant la blancheur de la couleur ou le mot-cl none (quivalent 0% dans ce cas) mlanger. 0% signifie aucune blancheur. 100% signifie blancheur totale si B vaut 0, sinon les valeurs de W et B sont normalises.
B: Un pourcentage (<percentage>) reprsentant la noirceur de la couleur ou le mot-cl none (quivalent 0% dans ce cas) mlanger. 0% signifie aucune noirceur. 100% signifie noirceur totale si W vaut 0, sinon les valeurs de W et B sont normalises.
A Facultatif: Une valeur <alpha-value> reprsentant la valeur du canal alpha de la couleur, o le nombre 0 correspond 0% (totalement transparent) et 1 100% (totalement opaque). De plus, le mot-cl none peut tre utilis pour indiquer explicitement l'absence de canal alpha. Si la valeur du canal A n'est pas explicitement dfinie, elle vaut par dfaut 100%. Si elle est prsente, la valeur est prcde d'une barre oblique (/).

Note : Voir Composantes de couleur manquantes pour plus d'informations sur l'effet de none.

Note : Les couleurs absolues hwb() sont srialises en valeurs rgb(). Les valeurs des composantes rouge, verte et bleue peuvent tre arrondies lors de la srialisation.

Syntaxe des valeurs relatives

hwb(from <color> H W B[ / A])

Les paramtres sont les suivants :

from <color>: Le mot-cl from est toujours inclus lors de la dfinition d'une couleur relative, suivi d'une valeur <color> reprsentant la couleur d'origine. Il s'agit de la couleur originale sur laquelle la couleur relative est base. La couleur d'origine peut tre n'importe quelle syntaxe <color> valide, y compris une autre couleur relative.
H: Un nombre (<number>), un angle (<angle>) ou le mot-cl none (quivalent 0deg dans ce cas) reprsentant l'angle de <hue> de la couleur de sortie.
W: Un pourcentage (<percentage>) reprsentant la blancheur de la couleur ou le mot-cl none (quivalent 0% dans ce cas) mlanger. 0% signifie aucune blancheur. 100% signifie blancheur totale si B vaut 0, sinon les valeurs de W et B sont normalises.
B: Un pourcentage (<percentage>) reprsentant la noirceur de la couleur ou le mot-cl none (quivalent 0% dans ce cas) mlanger. 0% signifie aucune noirceur. 100% signifie noirceur totale si W vaut 0, sinon les valeurs de W et B sont normalises.
A Facultatif: Une valeur <alpha-value> reprsentant la valeur du canal alpha de la couleur de sortie, o le nombre 0 correspond 0% (totalement transparent) et 1 100% (totalement opaque). De plus, le mot-cl none peut tre utilis pour indiquer explicitement l'absence de canal alpha. Si la valeur du canal A n'est pas explicitement dfinie, elle prend par dfaut la valeur du canal alpha de la couleur d'origine. Si elle est prsente, la valeur est prcde d'une barre oblique (/).

Note : Pour permettre la reprsentation complte de tout le spectre des couleurs visibles, la sortie des fonctions de couleur relatives hwb() est srialise en color(srgb). Cela signifie que la consultation de la valeur de couleur de sortie avec la proprit HTMLElement.style ou la mthode CSSStyleDeclaration.getPropertyValue() retourne la couleur de sortie sous forme de valeur color(srgb ...).

Dfinition des composants de canal de sortie des couleurs relatives

Lors de l'utilisation de la syntaxe de couleur relative dans une fonction hwb(), le navigateur convertit la couleur d'origine en couleur HWB quivalente (si elle n'est pas dj dfinie comme telle). La couleur est dfinie comme trois valeurs de canal de couleur distinctes h (teinte), w (blanc) et b (noir) plus une valeur de canal alpha (alpha). Ces valeurs de canal sont mises disposition dans la fonction pour tre utilises lors de la dfinition des valeurs de canal de couleur de sortie :

La valeur de canal h est rsolue en une valeur <number> entre 0 et 360, inclus.
Les canaux w et b sont chacun rsolus en une valeur <number> entre 0 et 100, inclus.
Le canal alpha est rsolu en une valeur <number> entre 0 et 1, inclus.

Lors de la dfinition d'une couleur relative, les diffrents canaux de la couleur de sortie peuvent tre exprims de plusieurs faons diffrentes. Ci-dessous, nous allons tudier quelques exemples pour illustrer ceci.

Dans les deux premiers exemples ci-dessous, nous utilisons la syntaxe de couleur relative. Cependant, le premier produit la mme couleur que la couleur d'origine et le second produit une couleur qui n'est pas du tout base sur la couleur d'origine. Ils ne crent pas vraiment de couleurs relatives ! Il est peu probable que vous les utilisiez dans du vrai code, et vous utiliseriez plutt une valeur de couleur absolue. Nous avons inclus ces exemples comme point de dpart pour apprendre la syntaxe hwb() relative.

Commenons par une couleur d'origine hsl(0 100% 50%) (quivalente hwb(0 0% 0%)). La fonction suivante produit la mme couleur que la couleur d'origine elle utilise les valeurs de canal h, w et b de la couleur d'origine (0, 0% et 0%) comme valeurs de canal de sortie :

css

hwb(from hsl(0 100% 50%) h w b)

La couleur de sortie de cette fonction est l'quivalent sRGB color() de hwb(0 0% 0%) : color(srgb 1 0 0).

La fonction suivante utilise des valeurs absolues pour les valeurs de canal de la couleur de sortie, produisant une couleur compltement diffrente, non base sur la couleur d'origine :

css

hwb(from hsl(0 100% 50%) 240 52% 12%)

Dans le cas ci-dessus, la couleur de sortie est l'quivalent sRGB color() de hwb(240 52% 12%) : color(srgb 0.52 0.52 0.88).

La fonction suivante cre une couleur relative, base sur la couleur d'origine :

css

hwb(from hsl(0 100% 50%) h 30% b)

Cet exemple :

Convertit la couleur d'origine (hsl(0 100% 50%)) en quivalent hwb() (hwb(0 0% 0%)).
Dfinit les valeurs de canal H et B pour la couleur de sortie celles des valeurs de canal H et B de l'quivalent hwb() de la couleur d'origine ces valeurs sont 0 et 0%, respectivement.
Dfinit la valeur de canal W de la couleur de sortie une nouvelle valeur non base sur la couleur d'origine : 30%.

La couleur de sortie finale est l'quivalent de hwb(0 30% 0%) dans l'espace de couleur sRGB color(srgb 1 0.3 0.3).

Note : Comme mentionn ci-dessus, si la couleur de sortie utilise un modle de couleur diffrent de la couleur d'origine, la couleur d'origine est convertie vers le mme modle ou espace que la couleur de sortie en arrire-plan afin qu'elle puisse tre reprsente de manire compatible (c'est--dire en utilisant les mmes canaux).

Dans les exemples que nous avons vus jusqu' prsent dans cette section, les canaux alpha n'ont pas t explicitement dfinis pour les couleurs d'origine ou de sortie. Lorsque le canal alpha de la couleur de sortie n'est pas dfini, il prend par dfaut la mme valeur que le canal alpha de la couleur d'origine. Lorsque le canal alpha de la couleur d'origine n'est pas dfini (et qu'il ne s'agit pas d'une couleur relative), il prend par dfaut la valeur 1. Par consquent, les valeurs de canal alpha d'origine et de sortie sont 1 pour les exemples ci-dessus.

Regardons quelques exemples qui dfinissent les valeurs de canal alpha d'origine et de sortie. Le premier dfinit que la valeur de canal alpha de sortie est la mme que la valeur de canal alpha d'origine, tandis que le second dfinit une valeur de canal alpha de sortie diffrente, non lie la valeur de canal alpha d'origine.

css

hwb(from hsl(0 100% 50% / 0.8) h w b / alpha)
/* Couleur de sortie calcule: color(srgb 1 0 0 / 0.8) */

hwb(from hsl(0 100% 50% / 0.8) h w b / 0.5)
/* Couleur de sortie calcule: color(srgb 1 0 0 / 0.5) */

Dans l'exemple suivant, la couleur d'origine hsl() est nouveau convertie en reprsentation hwb() hwb(0 0% 0%). Des calculs calc() sont appliqus aux valeurs H, W, B et A, et la couleur de sortie finale est l'quivalent de hwb(120 25% 10% / 0.9) dans l'espace de couleur sRGB : color(srgb 0.25 0.9 0.25 / 0.9).

css

hwb(from hsl(0 100% 50%) calc(h + 120) calc(w + 25) calc(b + 10) / calc(alpha - 0.1))

Note : Parce que les valeurs de canal de couleur d'origine sont rsolues en valeurs <number>, vous devez leur ajouter des nombres lors de leur utilisation dans des calculs, mme dans les cas o un canal accepterait normalement des valeurs <percentage>, <angle> ou d'autres types de valeurs. Ajouter un <percentage> un <number>, par exemple, ne fonctionne pas.

Syntaxe formelle

<hwb()> = 
  hwb( [ from <color> ]? [ <hue> | none ] [ <percentage> | <number> | none ] [ <percentage> | <number> | none ] [ / [ <alpha-value> | none ] ]? )  

<hue> = 
  <number>  |
  <angle>   

<alpha-value> = 
  <number>      |
  <percentage>

Cette syntaxe reflte le dernier standard selon CSS Color Module Level 4, CSS Color Module Level 5. Tous les navigateurs n'ont peut-tre pas implment toutes les parties. Voir la Compatibilit des navigateurs pour plus d'informations sur la prise en charge.

Exemples

Utilisation des couleurs relatives avec `hwb()`

Cet exemple met en forme trois lments HTML <div> avec des couleurs d'arrire-plan diffrentes. Celui du milieu reoit la --base-color non modifie, tandis que ceux de gauche et de droite reoivent des variantes claircie et assombrie de cette --base-color.

Ces variantes sont dfinies en utilisant des couleurs relatives la proprit personnalise --base-color est passe dans une fonction hwb(), et les couleurs de sortie ont leurs canaux blanc et noir modifis pour obtenir l'effet souhait avec une fonction calc(). La couleur claircie a 30% ajouts au canal blanc, et la couleur assombrie a 30% ajouts au canal noir.

<div id="container">
  <div class="item" id="one"></div>
  <div class="item" id="two"></div>
  <div class="item" id="three"></div>
</div>

CSS

#container {
  display: flex;
  width: 100vw;
  height: 100vh;
  box-sizing: border-box;
}

.item {
  flex: 1;
  margin: 20px;
}

css

:root {
  --base-color: orange;
}

/* Selon la spcification, les valeurs w et b devraient tre rsolues en un
   nombre entre 0-100.
   Cependant, Chrome 121+ les rsout incorrectement en nombres entre 0- d'o
   l'utilisation actuelle de calculs comme w + 0.3 au lieu de w + 30 */

#one {
  background-color: hwb(from var(--base-color) h calc(w + 0.3) b);
}

#two {
  background-color: var(--base-color);
}

#three {
  background-color: hwb(from var(--base-color) h w calc(b + 0.3));
}

/* Utilise @supports pour ajouter la prise en charge de l'ancienne syntaxe
   qui ncessite que les units % soient dfinies dans les calculs w et b.
   Ceci est requis pour Safari 16.4+. */
@supports (color: hwb(from red h w calc(b + 30%))) {
  #one {
    background-color: hwb(from var(--base-color) h calc(w + 30%) b);
  }

  #three {
    background-color: hwb(from var(--base-color) h w calc(b + 30%));
  }
}