# CSS: “font-display”: Property “font-display” doesn't exist.

> Canonical HTML version: https://rocketvalidator.com/html-validation/css-font-display-property-font-display-doesnt-exist
> Attribution: Rocket Validator (https://rocketvalidator.com)
> License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)

`font-display` controls how a font face is displayed based on whether and when it has been downloaded and is ready to use. Its accepted values — `auto`, `block`, `swap`, `fallback`, and `optional` — determine the behavior during the font-loading timeline (block period, swap period, and failure period). Because it governs the loading behavior of a font face definition, it only makes sense within a `@font-face` rule, not as a property applied to an HTML element.

When you place `font-display` inside a regular selector like `body` or `.heading`, the CSS validator correctly flags it as an unknown property. Browsers will silently ignore it, meaning your intended font-loading strategy won't take effect. Users may experience a flash of invisible text (FOIT) or other unwanted behavior because the browser falls back to its default font-display strategy.

## Why this matters

- **Font-loading performance:** Without a valid `font-display` descriptor in your `@font-face` rule, you lose control over how the browser handles text rendering while custom fonts load. Using `font-display: swap`, for example, ensures text remains visible with a fallback font until the custom font is ready — a key web performance best practice.
- **Standards compliance:** The CSS Fonts Module Level 4 specification defines `font-display` exclusively as a `@font-face` descriptor. Using it elsewhere produces invalid CSS.
- **Silent failure:** Browsers won't throw visible errors — they simply ignore the invalid property, which can make it difficult to diagnose why your font-loading behavior isn't working as expected.

## How to fix it

1. **Remove** `font-display` from any regular CSS rule (selectors like `body`, `h1`, `.class`, etc.).
2. **Add** `font-display` inside the `@font-face` at-rule where you define your custom font.
3. If you're loading fonts via a third-party service (like Google Fonts), you can often append a `&display=swap` parameter to the font URL instead of writing your own `@font-face` block.

## Examples

### ❌ Incorrect: `font-display` used as a CSS property

```css
body {
  font-family: "Open Sans", sans-serif;
  font-display: swap;
}
```

This triggers the validator error because `font-display` is not a valid CSS property for element selectors.

### ✅ Correct: `font-display` used inside `@font-face`

```css
@font-face {
  font-family: "Open Sans";
  src: url("/fonts/open-sans.woff2") format("woff2"),
       url("/fonts/open-sans.woff") format("woff");
  font-display: swap;
}

body {
  font-family: "Open Sans", sans-serif;
}
```

Here, `font-display: swap` is correctly placed inside the `@font-face` rule, telling the browser to immediately render text with a fallback font and then swap in "Open Sans" once it finishes loading.

### ✅ Correct: Using `display=swap` with Google Fonts

If you use Google Fonts, you don't need to write your own `@font-face` block. Instead, add the `display` parameter to the URL:

```html
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Open+Sans&display=swap">
```

Google Fonts will generate the `@font-face` rules with `font-display: swap` included automatically.

### ❌ Incorrect: `font-display` in a class selector

```css
.heading {
  font-family: "Roboto", sans-serif;
  font-display: optional;
}
```

### ✅ Correct: Separate the descriptor from the styling rule

```css
@font-face {
  font-family: "Roboto";
  src: url("/fonts/roboto.woff2") format("woff2");
  font-display: optional;
}

.heading {
  font-family: "Roboto", sans-serif;
}
```

The `font-display: optional` descriptor now correctly lives in the `@font-face` block, where it tells the browser to use the custom font only if it's already cached — otherwise, stick with the fallback. The `.heading` rule simply references the font family by name.