CSS :buffering Pseudo-Class

CSS :buffering Pseudo-Class

The CSS :buffering pseudo-class selects playable media elements, such as audio and video, when playback is temporarily interrupted because the browser is loading additional media data. It allows you to style media elements while they are buffering.

:buffering Syntax

:buffering {
  property: value;
}

The :buffering pseudo-class has no arguments. It can be attached to a media element selector to apply styles while that element is buffering.

Example Syntax

video:buffering {
  outline: 4px solid #e67e22;
}

This rule adds an orange outline to a video while it is buffering. When sufficient media data becomes available and playback resumes, the outline is removed automatically.

The selector responds to the media element's actual playback and loading state. It does not require a class to be added through JavaScript.

How :buffering Works

When a browser plays an audio or video resource, it may need to download additional data. If playback catches up with the available data, the media can temporarily stop while the browser continues loading.

The :buffering pseudo-class matches during this interruption when the media is expected to continue playing but does not yet have enough data.

Buffering Conditions

For HTML media elements, the browser determines this state using playback status, network activity, and media readiness.

Important: A buffering element also matches :playing. In CSS, the playing state includes temporary interruptions when playback is expected to resume automatically.

Elements That Match :buffering

The selector applies to elements capable of media playback. In HTML, the most common examples are <audio> and <video>.

Video Example

<video controls preload="metadata">
  <source src="video/sample.mp4" type="video/mp4">
  Your browser does not support the video element.
</video>

video:buffering {
  outline: 4px solid #e67e22;
}

If the video is playing and must wait for additional data, the browser can apply the outline during buffering.

Audio Example

<audio controls preload="metadata">
  <source src="audio/sample.mp3" type="audio/mpeg">
  Your browser does not support the audio element.
</audio>

audio:buffering {
  outline: 3px solid #e67e22;
}

The same pseudo-class works with audio elements. However, the exact buffering period depends on the media resource, network conditions, and browser behavior.

Simply downloading or preloading a media file does not necessarily cause :buffering to match. Playback must be requested, and the relevant buffering conditions must occur.

Related Media Pseudo-Classes

CSS provides several pseudo-classes for styling media according to its playback, loading, and sound states.

Buffering vs. Stalled

Both selectors describe interruptions caused by unavailable media data, but they distinguish between different loading conditions.

video:buffering {
  outline: 4px solid #e67e22;
}
video:stalled {
  outline: 4px solid #c0392b;
}

The first rule uses orange to indicate buffering. The second uses red when the browser identifies the loading process as stalled.

A stalled element can also be buffering. When both rules match, the later rule takes precedence because the selectors have equal specificity.

Practical Uses

The :buffering pseudo-class can provide visual feedback without requiring JavaScript to track every media loading event.

Highlighting a Buffering Video

video {
  max-width: 100%;
  border: 3px solid #ccc;
}
video:buffering {
  border-color: #e67e22;
}

The border changes color while the video is buffering and returns to its normal color when buffering ends.

Displaying a Buffering Message

A media element can be placed inside a wrapper that contains a message. The :has() pseudo-class can detect when the wrapper contains a buffering video.

HTML

<div class="video-wrapper">
  <video controls src="video/sample.mp4"></video>
  <p class="buffering-message" role="status">Buffering video...</p>
</div>

CSS

.buffering-message {
  display: none;
}
.video-wrapper:has(video:buffering) .buffering-message {
  display: block;
  color: #b45309;
  font-weight: bold;
}

The message becomes visible when the video matches :buffering. This approach requires browser support for both :buffering and :has().

CSS alone does not reliably announce dynamic state changes to assistive technologies. Use JavaScript and appropriate accessibility techniques if a spoken buffering notification is required.

Best Practices

• Use :buffering for temporary loading feedback rather than general media loading or download progress.
• Do not assume every media file will visibly enter the buffering state. Fast connections may prevent interruptions.
• Use :stalled when you need to distinguish a stalled download from ordinary buffering.
• Keep buffering indicators subtle and avoid large layout changes during playback.
• Do not rely on color alone to communicate important playback information.
• Provide a fallback for browsers that do not support the pseudo-class.
• Test using real media resources and different network conditions.
• Use JavaScript media events when more detailed playback information or accessible status announcements are required.

:buffering Example

This example adds an orange outline to a video while the browser is buffering. The video uses a sample media file, and the outline appears only if buffering occurs during playback.

HTML

<div class="buffering-demo">
  <video controls preload="metadata" width="280">
    <source src="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4" type="video/mp4">
    Your browser does not support the video element.
  </video>
  <p>Play the video to test the buffering state.</p>
</div>

CSS

.buffering-demo video {
  display: block;
  max-width: 100%;
  border: 3px solid #999;
}
.buffering-demo video:buffering {
  border-color: #e67e22;
  outline: 3px solid #e67e22;
  outline-offset: 3px;
}
.buffering-demo video:stalled {
  border-color: #c0392b;
  outline-color: #c0392b;
}
.buffering-demo p {
  margin-top: 12px;
  color: #555;
}

Browser Result

Play the video below. If playback must wait for additional data, the border and outline turn orange. A stalled download may produce a red indicator. On a fast connection, the video may play without a noticeable buffering period.

Play in Editor

Note: The browser result depends on actual media loading conditions. It is normal for the buffering style not to appear during a short, fully loaded video.

Browser Support

Baseline: Newly available. The :buffering pseudo-class became available across the latest major browser versions in August 2026. Older browsers may not support it.

Browsers that do not recognize :buffering ignore rules using that selector. The media element itself continues to function normally.

For current compatibility information, visit Can I Use? and search for CSS :buffering.

Specifications

The :buffering pseudo-class is defined in Selectors Level 4 and the HTML Living Standard.

Selectors Level 4 - The :buffering Pseudo-Class

HTML Living Standard - :buffering