CSS hwb() Function

CSS hwb() Function

The CSS hwb() function defines colors using hue, whiteness, and blackness, with an optional alpha value for transparency.

HWB provides an intuitive way to create lighter, darker, or muted variations of a color by adjusting the amounts of white and black. The function produces colors in the sRGB color space and can be used anywhere a CSS <color> value is accepted.

Syntax

hwb(hue whiteness blackness)
hwb(hue whiteness blackness / alpha)
hwb(from color hue whiteness blackness)
hwb(from color hue whiteness blackness / alpha)

The function uses space-separated components. An optional alpha value is preceded by a slash.

For example:

.box {
  background-color: hwb(210 20% 10%);
}

This creates a blue color with 20% whiteness and 10% blackness.

Additional examples:

color: hwb(0 0% 0%);
color: hwb(120 20% 10%);
color: hwb(240 30% 20%);
color: hwb(210 20% 10% / 50%);
color: hwb(180deg 10% 20%);
color: hwb(0.5turn 10% 20%);

Unlike hsl(), the hwb() function does not have a legacy comma-separated syntax.

The function returns a CSS <color> value.

Parameters

The hwb() function uses three color components and an optional alpha component.

For example:

hwb(210 25% 15% / 0.8)

This defines a blue color with 25% whiteness, 15% blackness, and 80% opacity.

Whiteness and blackness are commonly written as percentages. Modern CSS Color syntax also allows numeric values, where 100 corresponds to 100%.

The none keyword can represent a missing component.

How It Works

The hwb() function starts with a fully saturated hue and adjusts it by adding whiteness and blackness.

The process can be understood in four steps:

1. Hue selects the starting color on the color wheel.
2. Whiteness adds white to the starting color.
3. Blackness adds black to the starting color.
4. The optional alpha value controls transparency.

For example:

hwb(210 0% 0%)
hwb(210 30% 0%)
hwb(210 0% 30%)
hwb(210 30% 30%)

The first produces a fully saturated blue. The second creates a lighter variation, the third creates a darker variation, and the fourth creates a more muted color.

When whiteness and blackness are both zero, the result matches an HSL color with 100% saturation and 50% lightness.

hwb(210 0% 0%)
hsl(210 100% 50%)

These expressions define the same color.

Hue

Hue identifies the starting color using a position on the color wheel.

The hue angles are the same as those used by hsl().

Hue values wrap around the color wheel, so 0 degrees and 360 degrees represent the same hue.

Hue can use deg, rad, grad, or turn units.

hwb(180deg 0% 0%)
hwb(0.5turn 0% 0%)

Both expressions produce cyan.

Whiteness

Whiteness controls how much white is mixed into the selected hue.

Increasing whiteness generally produces a lighter, less saturated color when blackness remains unchanged.

For example:

hwb(210 0% 0%)
hwb(210 20% 0%)
hwb(210 40% 0%)
hwb(210 60% 0%)
hwb(210 80% 0%)
hwb(210 100% 0%)

The colors progress from a saturated blue toward white.

When whiteness is 100% and blackness is 0%, the result is white regardless of hue.

For example:

hwb(0 100% 0%)
hwb(120 100% 0%)
hwb(240 100% 0%)

All three produce white.

Whiteness is useful for creating pale backgrounds, subtle highlights, and lighter color variations.

Blackness

Blackness controls how much black is mixed into the selected hue.

Increasing blackness generally produces a darker color when whiteness remains unchanged.

For example:

hwb(210 0% 0%)
hwb(210 0% 20%)
hwb(210 0% 40%)
hwb(210 0% 60%)
hwb(210 0% 80%)
hwb(210 0% 100%)

The colors progress from saturated blue toward black.

When blackness is 100% and whiteness is 0%, the result is black regardless of hue.

For example:

hwb(0 0% 100%)
hwb(120 0% 100%)
hwb(240 0% 100%)

All three produce black.

Blackness is useful for darker backgrounds, borders, and related color variations.

Combining Whiteness and Blackness

Whiteness and blackness can be adjusted together to create muted colors and shades of gray.

For example:

hwb(210 10% 10%)
hwb(210 20% 20%)
hwb(210 30% 30%)
hwb(210 40% 40%)
hwb(210 50% 50%)

As both values increase, less of the original hue remains visible.

When whiteness and blackness add up to 100% or more, the result is a shade of gray and the hue no longer affects the visible color.

For example:

hwb(0 50% 50%)
hwb(120 50% 50%)
hwb(240 50% 50%)

All three produce the same medium gray.

If the total exceeds 100%, the browser normalizes the whiteness and blackness values proportionally.

For example:

hwb(210 40% 80%)

The total is 120%. The resulting gray has an RGB channel value of approximately 33.33%, calculated as 40 divided by 120.

The specified values are valid, even though their sum exceeds 100%.

Alpha and Transparency

The optional alpha component controls the opacity of an HWB color.

Use a slash before the alpha value:

background-color: hwb(210 20% 10% / 50%);

This creates a blue color with 50% opacity.

Alpha accepts numbers or percentages:

hwb(210 20% 10% / 1)
hwb(210 20% 10% / 0.75)
hwb(210 20% 10% / 0.5)
hwb(210 20% 10% / 0)
hwb(210 20% 10% / 50%)

An alpha value of 1 or 100% is fully opaque. An alpha value of 0 is fully transparent.

If alpha is omitted, the color is fully opaque in absolute HWB syntax.

Alpha changes transparency without changing the underlying hue, whiteness, or blackness components.

Relative HWB Colors

Relative color syntax allows a new HWB color to be created from an existing color.

The syntax begins with the from keyword:

hwb(from origin-color hue whiteness blackness)
hwb(from origin-color hue whiteness blackness / alpha)

For example:

.button {
  --base-color: hwb(210 10% 15%);
  background-color: hwb(from var(--base-color) h calc(w + 20) b);
}

The browser extracts the original HWB components and increases whiteness by 20 percentage points.

Relative HWB syntax provides four channel keywords:

For example:

hwb(from red h w b)
hwb(from red h calc(w + 20) b)
hwb(from red h w calc(b + 20))
hwb(from red calc(h + 180) w b)
hwb(from red h w b / 0.5)

These expressions preserve the original color, increase whiteness, increase blackness, rotate hue, or change opacity.

Relative channel calculations use numbers rather than percentages. For example, calc(w + 20) adds 20 percentage points to the original whiteness.

If alpha is omitted in relative color syntax, the original color's alpha is preserved.

Relative color syntax has different browser compatibility requirements from basic hwb() syntax.

Missing Color Components

The hwb() function supports the none keyword to represent a missing color component.

For example:

hwb(none 20% 10%)
hwb(210 none 10%)
hwb(210 20% none)
hwb(210 20% 10% / none)

When a missing component is used to render a color directly, it behaves like zero for that component.

For example:

hwb(210 none 10%)

This renders like hwb(210 0% 10%).

Missing components can also affect color interpolation, allowing corresponding components to be taken from another color.

For ordinary color definitions, explicit values are generally easier to understand and maintain.

Using Custom Properties

CSS custom properties can store complete HWB colors or individual color components.

For example:

:root {
  --primary-color: hwb(210 15% 20%);
}
.button {
  background-color: var(--primary-color);
}

This allows the same color to be reused throughout a stylesheet.

Individual components can also be stored:

:root {
  --hue: 210;
  --whiteness: 15%;
  --blackness: 20%;
}
.button {
  background-color: hwb(var(--hue) var(--whiteness) var(--blackness));
}

Changing a custom property updates every declaration that uses it.

For example:

.button:hover {
  background-color: hwb(var(--hue) 25% var(--blackness));
}

This increases the whiteness to create a lighter variation of the button color.

Example

This example demonstrates six base hues using zero whiteness and zero blackness.

HTML:

<div class="hwb-demo">
  <div class="hwb-demo-item"><div class="hwb-demo-color hwb-red"></div><span>0° Red</span></div>
  <div class="hwb-demo-item"><div class="hwb-demo-color hwb-yellow"></div><span>60° Yellow</span></div>
  <div class="hwb-demo-item"><div class="hwb-demo-color hwb-green"></div><span>120° Green</span></div>
  <div class="hwb-demo-item"><div class="hwb-demo-color hwb-cyan"></div><span>180° Cyan</span></div>
  <div class="hwb-demo-item"><div class="hwb-demo-color hwb-blue"></div><span>240° Blue</span></div>
  <div class="hwb-demo-item"><div class="hwb-demo-color hwb-magenta"></div><span>300° Magenta</span></div>
</div>

CSS:

.hwb-demo {
  display: grid;
  grid-template-columns: repeat(3, minmax(0, 1fr));
  gap: 12px;
  max-width: 420px;
  margin: 0 auto;
}
.hwb-demo-item {
  text-align: center;
  font-size: 13px;
}
.hwb-demo-color {
  height: 65px;
  margin-bottom: 6px;
  border-radius: 4px;
}
.hwb-red { background-color: hwb(0 0% 0%); }
.hwb-yellow { background-color: hwb(60 0% 0%); }
.hwb-green { background-color: hwb(120 0% 0%); }
.hwb-cyan { background-color: hwb(180 0% 0%); }
.hwb-blue { background-color: hwb(240 0% 0%); }
.hwb-magenta { background-color: hwb(300 0% 0%); }

Each swatch uses 0% whiteness and 0% blackness. Only the hue changes.

These colors are equivalent to HSL colors with 100% saturation and 50% lightness.

Whiteness Example

This example demonstrates how increasing whiteness produces lighter variations of the same hue.

HTML:

<div class="hwb-white-demo">
  <div class="hwb-white-item hwb-white-0">0%</div>
  <div class="hwb-white-item hwb-white-20">20%</div>
  <div class="hwb-white-item hwb-white-40">40%</div>
  <div class="hwb-white-item hwb-white-60">60%</div>
  <div class="hwb-white-item hwb-white-80">80%</div>
</div>

CSS:

.hwb-white-demo {
  display: flex;
  flex-wrap: wrap;
  justify-content: center;
  gap: 8px;
}
.hwb-white-item {
  display: grid;
  place-items: center;
  width: 65px;
  height: 65px;
  color: #111;
  font-size: 13px;
}
.hwb-white-0 { background-color: hwb(210 0% 0%); color: #fff; }
.hwb-white-20 { background-color: hwb(210 20% 0%); color: #fff; }
.hwb-white-40 { background-color: hwb(210 40% 0%); }
.hwb-white-60 { background-color: hwb(210 60% 0%); }
.hwb-white-80 { background-color: hwb(210 80% 0%); }

All five swatches use a hue of 210 degrees and 0% blackness.

Increasing whiteness creates progressively lighter shades of blue. Text colors are adjusted on the lighter swatches for readability.

Blackness Example

This example demonstrates how increasing blackness produces darker variations of the same hue.

HTML:

<div class="hwb-black-demo">
  <div class="hwb-black-item hwb-black-0">0%</div>
  <div class="hwb-black-item hwb-black-20">20%</div>
  <div class="hwb-black-item hwb-black-40">40%</div>
  <div class="hwb-black-item hwb-black-60">60%</div>
  <div class="hwb-black-item hwb-black-80">80%</div>
</div>

CSS:

.hwb-black-demo {
  display: flex;
  flex-wrap: wrap;
  justify-content: center;
  gap: 8px;
}
.hwb-black-item {
  display: grid;
  place-items: center;
  width: 65px;
  height: 65px;
  color: #fff;
  font-size: 13px;
}
.hwb-black-0 { background-color: hwb(210 0% 0%); }
.hwb-black-20 { background-color: hwb(210 0% 20%); }
.hwb-black-40 { background-color: hwb(210 0% 40%); }
.hwb-black-60 { background-color: hwb(210 0% 60%); }
.hwb-black-80 { background-color: hwb(210 0% 80%); }

All five swatches use a hue of 210 degrees and 0% whiteness.

Increasing blackness creates progressively darker shades of blue.

hwb() vs. hsl()

The hwb() and hsl() functions both define colors in the sRGB color space, but they use different components.

For example, these represent the same red color:

color: hwb(0 0% 0%);
color: hsl(0 100% 50%);
color: rgb(255 0 0);

Use hwb() when you want to adjust a color by adding whiteness or blackness. Use hsl() when you want to work directly with saturation and lightness.

Neither function automatically guarantees accessible color contrast.

Common Uses

The hwb() function is useful for defining and adjusting colors in CSS.

For example:

.button {
  background-color: hwb(210 10% 20%);
  color: #fff;
}
.button:hover {
  background-color: hwb(210 10% 35%);
}

The hover state uses the same hue and whiteness with increased blackness.

Limitations

The hwb() function has several important rules and limitations.

• Hue, whiteness, and blackness are required components, although none can represent a missing component.
• The components are separated by spaces, with a slash before optional alpha.
• Comma-separated syntax is not supported.
• Hue values wrap around the color wheel.
• Whiteness and blackness can total more than 100% without making the color invalid.
• When whiteness and blackness total 100% or more, the resulting color is gray and hue no longer affects it.
• HWB uses sRGB and does not directly define colors outside that color space.
• Whiteness and blackness are not direct measurements of perceived brightness.
• Relative color syntax may have different browser support from basic HWB syntax.

For example, this is valid:

color: hwb(210 40% 80%);

The browser normalizes the whiteness and blackness values because their sum exceeds 100%.

The following is invalid because it uses commas:

color: hwb(210, 20%, 10%);

The following is invalid because a required component is missing:

color: hwb(210 20%);

Use three space-separated color components and an optional alpha value.

Browser Support

The CSS hwb() function is Baseline Widely available. It has been supported across major browser engines since April 2022.

It works in current versions of Chrome, Edge, Firefox, Safari, and other modern browsers.

Relative color syntax using hwb(from ...) is a newer feature and has separate compatibility requirements.

For example:

.box {
  background-color: hwb(210 20% 10%);
}

For older browsers, an equivalent RGB or HSL fallback can be provided before the HWB declaration:

.box {
  background-color: rgb(51 140 230);
  background-color: hwb(210 20% 10%);
}

For current compatibility information, visit Can I Use? and search for CSS hwb(). Check relative color syntax separately when using from.

Specifications

The hwb() function is defined in the CSS Color Module Level 4 .

Relative HWB color syntax is defined in the CSS Color Module Level 5 .

These specifications define HWB color components, alpha values, missing components, color conversion, and relative color calculations.

Related CSS functions include hsl(), rgb(), lab(), lch(), oklch(), and color-mix().