CSS grayscale() Function

CSS grayscale() Function

The CSS grayscale() function converts the colors of an image or element to shades of gray, with an adjustable amount of the effect.

It is used with the filter and backdrop-filter properties. The function can remove all color or create a partially desaturated appearance without modifying the original image file.

Syntax

grayscale()
grayscale(amount)

The optional amount parameter determines how much color is removed.

For example:

.image {
  filter: grayscale(100%);
}

This converts the image to grayscale.

Additional examples:

filter: grayscale(0);
filter: grayscale(0.25);
filter: grayscale(50%);
filter: grayscale(1);
filter: grayscale(100%);
filter: grayscale();

If the argument is omitted, the default is 1, equivalent to 100%.

The function returns a CSS <filter-function> value.

Parameters

The grayscale() function accepts one optional parameter.

For example:

grayscale(0.5)
grayscale(50%)

Both expressions produce a 50% grayscale effect.

Important rules include:

• 0 or 0% leaves the colors unchanged.
• 1 or 100% produces complete grayscale.
• Values between zero and one produce partial grayscale.
• Values above one are allowed but the effect is limited to complete grayscale.
• Negative values are invalid.
• An omitted argument defaults to complete grayscale.

The default argument should not be confused with the no-effect value used when interpolating from an unfiltered state.

How It Works

The grayscale() function adjusts the color components of the rendered image to reduce color saturation and produce gray tones.

The process works as follows:

1. The browser renders the element or image.
2. The grayscale filter calculates adjusted color values.
3. The specified amount determines how strongly the grayscale conversion is applied.
4. The filtered result is displayed without changing the original image file.

For example:

.photo {
  filter: grayscale(75%);
}

This removes most of the visible color while retaining some of the original color information.

The conversion uses weighted color components rather than simply averaging red, green, and blue equally.

The result is a visual effect applied during rendering. The original source image remains unchanged.

Grayscale Values

Different values produce different levels of grayscale.

For example:

.original {
  filter: grayscale(0);
}
.partial {
  filter: grayscale(50%);
}
.full {
  filter: grayscale(100%);
}

The first retains the original colors, the second partially removes color, and the third displays the result entirely in shades of gray.

Numbers and Percentages

The grayscale() function accepts either numbers or percentages.

Equivalent values include:

For example:

filter: grayscale(0.6);
filter: grayscale(60%);

Both declarations produce the same effect.

Values above 1 or 100% are accepted but produce no stronger effect than complete grayscale.

For example:

filter: grayscale(150%);

This produces the same visible grayscale amount as grayscale(100%).

Using grayscale() with filter

The filter property applies grayscale to the rendered appearance of an element.

For example:

.photo {
  filter: grayscale(100%);
}

This converts the entire image to grayscale.

The effect can also be applied to a container:

.card {
  filter: grayscale(100%);
}

In this case, the filter affects the card's rendered appearance, including its background, text, images, and descendants.

The function does not alter the underlying CSS color values or the original image files.

Use filter: none; to remove the effect entirely.

Using grayscale() with backdrop-filter

The backdrop-filter property applies a grayscale effect to the area behind an element rather than to the element's own content.

For example:

.overlay {
  background-color: rgb(255 255 255 / 20%);
  backdrop-filter: grayscale(100%);
}

The content visible through the overlay appears in grayscale while the overlay's own content is not directly filtered.

The overlay must have a transparent or partially transparent background for the effect behind it to be visible.

Another example:

.glass-panel {
  background-color: rgb(255 255 255 / 15%);
  backdrop-filter: grayscale(80%) blur(4px);
}

This reduces the color and blurs the area behind the panel.

Browser support for backdrop-filter is separate from support for the grayscale() function itself.

Combining Filters

The grayscale() function can be combined with other CSS filter functions.

For example:

.photo {
  filter: grayscale(100%) contrast(120%);
}

This converts the image to grayscale and increases its contrast.

Another example:

.photo {
  filter: grayscale(60%) brightness(110%);
}

This partially removes color and increases brightness.

Common combinations include:

Filter functions are applied in the order they appear.

Changing their order can change the final result, particularly when combining different color effects.

Transitions and Hover Effects

The grayscale() function can be animated with CSS transitions.

For example:

.photo {
  filter: grayscale(100%);
  transition: filter 0.4s ease;
}
.photo:hover {
  filter: grayscale(0);
}

The image begins in grayscale and gradually returns to its original colors when hovered.

For keyboard-accessible interactive elements, include :focus-visible:

.photo-link img {
  filter: grayscale(100%);
  transition: filter 0.4s ease;
}
.photo-link:hover img,
.photo-link:focus-visible img {
  filter: grayscale(0);
}

To respect reduced-motion preferences:

@media (prefers-reduced-motion: reduce) {
  .photo-link img {
    transition: none;
  }
}

Using the same filter function in both states allows the grayscale amount to interpolate smoothly.

Example

This example compares an original colorful design with 50% grayscale and complete grayscale.

HTML:

<div class="grayscale-demo">
  <div class="grayscale-demo-item">
    <div class="grayscale-demo-art grayscale-original">
      <span>CSS</span>
    </div>
    <p>Original</p>
  </div>
  <div class="grayscale-demo-item">
    <div class="grayscale-demo-art grayscale-half">
      <span>CSS</span>
    </div>
    <p>50% Grayscale</p>
  </div>
  <div class="grayscale-demo-item">
    <div class="grayscale-demo-art grayscale-full">
      <span>CSS</span>
    </div>
    <p>100% Grayscale</p>
  </div>
</div>

CSS:

.grayscale-demo {
  display: flex;
  flex-wrap: wrap;
  justify-content: center;
  gap: 15px;
  padding: 15px 0;
}
.grayscale-demo-item {
  width: 125px;
  text-align: center;
}
.grayscale-demo-item p {
  margin: 8px 0 0;
  font-size: 13px;
}
.grayscale-demo-art {
  display: grid;
  place-items: center;
  height: 95px;
  background: linear-gradient(135deg, #0066cc 0%, #e83e8c 50%, #ffc107 100%);
  border-radius: 6px;
}
.grayscale-demo-art span {
  color: #fff;
  font-size: 25px;
  font-weight: bold;
}
.grayscale-original {
  filter: grayscale(0);
}
.grayscale-half {
  filter: grayscale(50%);
}
.grayscale-full {
  filter: grayscale(100%);
}

The first design retains its original colors. The second shows partially reduced color, while the third is completely grayscale.

The grayscale filter also affects the white text, although white remains visually unchanged when converted to grayscale.

Hover Example

This example uses a CSS transition to reveal the original colors when a card is hovered or receives keyboard focus.

HTML:

<button class="grayscale-hover-demo" type="button">
  <span class="grayscale-hover-art">CSS</span>
  <span class="grayscale-hover-label">Hover or Focus to Reveal Color</span>
</button>

CSS:

.grayscale-hover-demo {
  display: block;
  width: 240px;
  max-width: 100%;
  margin: 0 auto;
  padding: 0;
  overflow: hidden;
  border: 0;
  border-radius: 6px;
  background-color: #fff;
  cursor: pointer;
}
.grayscale-hover-art {
  display: grid;
  place-items: center;
  height: 120px;
  background: linear-gradient(135deg, #0066cc, #e83e8c, #ffc107);
  color: #fff;
  font-size: 32px;
  font-weight: bold;
  filter: grayscale(100%);
  transition: filter 0.4s ease;
}
.grayscale-hover-label {
  display: block;
  padding: 10px;
  color: #333;
  font-size: 13px;
}
.grayscale-hover-demo:hover .grayscale-hover-art,
.grayscale-hover-demo:focus-visible .grayscale-hover-art {
  filter: grayscale(0);
}
@media (prefers-reduced-motion: reduce) {
  .grayscale-hover-art {
    transition: none;
  }
}

The design begins in grayscale. Hovering over the card or focusing it with the keyboard restores the original colors.

The transition is disabled for users who prefer reduced motion.

grayscale() vs. saturate()

The grayscale() and saturate() functions can both reduce visible color, but their values work differently.

For example:

.gray {
  filter: grayscale(100%);
}
.desaturated {
  filter: saturate(0);
}

Both produce a fully desaturated appearance.

Use grayscale() when you want to specify how much grayscale is applied. Use saturate() when you want to decrease or increase saturation.

Accessibility

Grayscale effects can change how easily users distinguish content.

Consider the following guidelines:

• Do not rely on color or grayscale alone to communicate status or meaning.
• Check text contrast after applying grayscale filters.
• Keep important controls identifiable without color.
• Do not make essential information available only on hover.
• Provide keyboard focus behavior for interactive hover effects.
• Respect reduced-motion preferences when animating filters.

For example, applying grayscale to a disabled-looking button does not actually disable the button.

.disabled-look {
  filter: grayscale(100%);
}

Use the appropriate HTML disabled state or other semantic behavior when an interactive control must be unavailable.

Grayscale is a visual effect, not an accessibility state.

Common Uses

The grayscale() function is useful for creating monochrome designs and interactive visual effects.

For example:

.portfolio-thumbnail {
  filter: grayscale(100%);
  transition: filter 0.3s ease;
}
.portfolio-thumbnail:hover {
  filter: grayscale(0);
}

This creates a grayscale-to-color hover effect for a portfolio thumbnail.

Limitations

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

• The argument must be a number or percentage.
• Negative values are invalid.
• Values above 100% are allowed but cannot increase the effect beyond complete grayscale.
• Omitting the argument applies complete grayscale.
• The filter affects the rendered appearance, not the original image file.
• Applying the filter to a container also affects its rendered descendants.
• The filter does not change the layout dimensions of an element.
• Large or frequently animated filtered areas may require additional rendering work.
• Using backdrop-filter requires separate browser support.

For example, this is valid:

filter: grayscale(75%);

The following is invalid because the amount is negative:

filter: grayscale(-50%);

The following is invalid because the function does not accept a length:

filter: grayscale(20px);

Use a unitless number or percentage to specify the amount.

Browser Support

The CSS grayscale() function is Baseline Widely available. It has been supported across major browser engines since September 2016.

It works in current versions of Chrome, Edge, Firefox, Safari, and other modern browsers when used with the filter property.

Support for backdrop-filter became Baseline Newly available in September 2024 and may differ on older browsers.

For example:

.image {
  filter: grayscale(100%);
}

For current compatibility information, visit Can I Use? .

Specifications

The grayscale() function is defined in the Filter Effects Module Level 1 .

The specification defines the grayscale filter operation, accepted values, and interpolation behavior.

Related CSS functions include brightness(), contrast(), invert(), saturate(), and sepia().