CSS :volume-locked Pseudo-Class

CSS :volume-locked Pseudo-Class

The CSS :volume-locked pseudo-class selects media elements whose audio volume is locked by the browser or user settings. It applies to sound-capable elements such as <audio> and <video> when a webpage cannot change their volume or muted state through JavaScript. This selector allows developers to provide visual feedback when audio volume is controlled outside the webpage.

:volume-locked Syntax

:volume-locked {
  property: value;
}

The :volume-locked pseudo-class matches a media element when its audio volume is locked by the browser or user agent.

Basic Example

video:volume-locked {
  border: 3px solid #b45309;
}

Adds an orange border to a video element when its volume is locked.

Audio Elements

audio:volume-locked {
  outline: 3px solid #b45309;
}

Multiple Media Elements

audio:volume-locked,
video:volume-locked {
  outline: 3px solid #b45309;
}

Class Selector

.media-player:volume-locked {
  border-color: #b45309;
}

No Arguments

The pseudo-class is written as :volume-locked, without parentheses or arguments.

How :volume-locked Works

The browser determines whether the audio volume of a media element is locked. When the volume is locked, the element matches :volume-locked.

Step 1 - Create a Media Element

<audio controls src="audio/sample.mp3">
  Your browser does not support audio playback.
</audio>

Step 2 - Add Volume-Locked Styling

audio:volume-locked {
  outline: 3px solid #b45309;
  outline-offset: 3px;
}

Step 3 - Browser Determines Volume State

The browser or operating system may enforce volume settings that prevent the webpage from changing the media element's volume.

Step 4 - Apply the Matching Style

If the media element's volume is locked, the browser applies the CSS declarations associated with :volume-locked.

Step 5 - Respond to State Changes

If the browser changes the volume-lock state, selector matching can update automatically.

No JavaScript Required

CSS can style the locked state without JavaScript. However, CSS cannot enable, disable, or override the volume lock.

Supported Media Elements

The :volume-locked pseudo-class is intended for media elements capable of producing sound.

Audio Elements

<audio controls src="audio/sample.mp3">
  Your browser does not support audio playback.
</audio>

The <audio> element can match :volume-locked when the browser prevents the webpage from changing its volume.

Video Elements

<video controls width="300" src="video/sample.mp4">
  Your browser does not support video playback.
</video>

The <video> element can also match the selector when its audio volume is locked.

Element Comparison

Media Source Files

The selector does not depend on a particular audio or video file format. It depends on the browser's volume-lock state for the media element.

Volume Control

Webpages normally control media volume through the HTML media API. A volume lock restricts that control.

Normal Volume Control

const player = document.querySelector("audio");
player.volume = 0.5;

Normally, this requests a volume level of 50% for the selected audio element.

Muted State

const player = document.querySelector("audio");
player.muted = true;

Normally, this requests that the audio element be muted.

Locked Volume

When the volume is locked, the webpage cannot override the browser's effective volume or muted state through these properties.

User Agent Control

A browser may enforce volume preferences based on device capabilities, operating system behavior, or user settings.

CSS Cannot Unlock Volume

The :volume-locked pseudo-class only selects elements. It does not provide a way to change the lock.

Not an HTML Attribute

There is no standard volume-locked HTML attribute that authors can add to an audio or video element to activate this pseudo-class.

:muted vs. :volume-locked

The :muted and :volume-locked pseudo-classes describe different audio states.

Muted Media

video:muted {
  border: 3px solid #006699;
}

Volume-Locked Media

video:volume-locked {
  border: 3px solid #b45309;
}

Both States

video:muted:volume-locked {
  border-color: #663399;
}

A media element can be muted and volume-locked at the same time.

Volume Level vs. Volume Lock

A volume level of zero does not automatically mean the volume is locked. Likewise, a volume lock does not necessarily mean the media is silent.

JavaScript Media Properties

The HTMLMediaElement interface provides properties for working with audio and video playback.

Reading Media Properties

const player = document.querySelector("audio");
console.log(player.volume);
console.log(player.muted);

Locked Volume Behavior

When the browser enforces a volume lock, JavaScript cannot override the effective audio level or muted state. Reading the volume property does not necessarily reveal the final volume enforced by the operating system.

No Standard Unlock Method

The HTMLMediaElement interface does not provide a standard method for webpages to remove a browser-enforced volume lock.

Testing Selector Support

const supported = CSS.supports("selector(:volume-locked)");
console.log(supported);

This checks whether the browser recognizes the selector. It does not indicate whether a particular media element is currently volume-locked.

Practical Uses

The :volume-locked pseudo-class can provide visual information about browser-controlled media volume.

Highlight a Locked Player

audio:volume-locked {
  outline: 3px solid #b45309;
}

Video Player Border

video:volume-locked {
  border: 3px solid #b45309;
}

Style a Player Container

.media-wrapper:has(audio:volume-locked) {
  border: 2px solid #b45309;
}

The :has() pseudo-class allows a container to be styled when it contains a volume-locked audio element.

Display a Status Message

.media-wrapper .volume-message {
  display: none;
}
.media-wrapper:has(audio:volume-locked) .volume-message {
  display: block;
}

A message already present in the HTML can become visible when the audio element matches :volume-locked.

Media Player Interfaces

Custom player interfaces can use the selector to distinguish browser-enforced audio restrictions from normal playback states.

:volume-locked Specificity

The :volume-locked pseudo-class contributes a specificity of 0-1-0, like other standard pseudo-classes.

Specificity Examples

Specificity Example

audio {
  outline: 2px solid #999;
}
audio:volume-locked {
  outline-color: #b45309;
}

The second selector has higher specificity and changes the outline color when the audio element is volume-locked, assuming other cascade factors are equal.

Limitations

The :volume-locked pseudo-class identifies a browser-controlled state and cannot create that state itself.

Cannot Force a Volume Lock

CSS cannot lock the volume of an audio or video element.

Cannot Unlock Volume

CSS and ordinary webpage scripts cannot override a browser-enforced volume lock.

Not the Same as Muted

The selector does not indicate whether audio is currently audible or silent.

Browser-Dependent State

Whether a media element becomes volume-locked depends on the browser, operating system, and applicable user preferences.

Limited Control Over Testing

There is no standard HTML attribute or JavaScript method that forces a media element into the volume-locked state for demonstration purposes.

Browser Support Differences

Older browsers may not recognize the selector, and browser implementations can differ in how volume locking is exposed.

No Playback Requirement

The media element does not need to be actively playing to match :volume-locked.

Accessibility

Media controls and status information should remain understandable when audio volume is restricted by the browser or operating system.

Do Not Rely on Color Alone

An orange border can indicate a locked state visually, but important status information should also be communicated through text.

Provide Descriptive Messages

If a custom player displays a volume-lock notice, explain that volume is controlled by browser or device settings.

Maintain Keyboard Access

Keep playback controls accessible by keyboard even when the webpage cannot adjust the audio volume.

Avoid Misleading Controls

Do not suggest that a webpage volume control can override an enforced volume lock.

Preserve Native Controls

Native media controls can provide familiar playback interactions and accessibility features.

Screen Reader Considerations

CSS styling does not automatically announce the volume-locked state to assistive technology. Important status information should be provided through accessible content.

Best Practices

• Use :volume-locked only for media elements that can produce sound.
• Use the selector to provide visual feedback rather than attempting to control the volume lock.
• Remember that a locked volume does not necessarily mean the media is muted.
• Use :muted when styling the muted state.
• Provide readable text when a volume-lock notice is important.
• Keep native or custom playback controls accessible.
• Do not assume that every browser or operating system exposes the same volume-lock behavior.
• Test with actual browser or device settings when possible.
• Provide normal player styling when :volume-locked is unsupported or does not match.
• Do not rely on CSS to enforce audio volume restrictions.

:volume-locked Example

This example styles an audio player when the browser reports that its volume is locked. The audio element receives an orange outline and a status message appears when the selector matches. Because volume locking is controlled by the browser or operating system, the effect cannot be activated simply by clicking a button on the page.

HTML

<div class="volume-demo">
  <div class="media-wrapper">
    <audio controls preload="none">
      <source src="audio/sample.mp3" type="audio/mpeg">
      Your browser does not support audio playback.
    </audio>
    <p class="volume-message">Audio volume is locked by your browser or device settings.</p>
  </div>
</div>

CSS

.volume-demo .media-wrapper {
  padding: 10px;
  border: 2px solid #ccc;
}
.volume-demo audio {
  display: block;
  width: 100%;
}
.volume-demo audio:volume-locked {
  outline: 3px solid #b45309;
  outline-offset: 3px;
}
.volume-demo .volume-message {
  display: none;
  margin: 12px 0 0;
  color: #8a4200;
  font-weight: bold;
}
.volume-demo .media-wrapper:has(audio:volume-locked) .volume-message {
  display: block;
}

Browser Result

Play in Editor

Note: The volume-locked styling appears only when the browser reports a locked volume state. In normal circumstances, the audio player will retain its default styling. The example does not force a volume lock.

Browser Support

Baseline: Newly available. The :volume-locked pseudo-class is part of the CSS media state selectors supported in recent browser releases. Support and actual volume-lock behavior can vary between browsers and operating systems.

For current compatibility information, visit Can I Use? .

Specifications

The :volume-locked pseudo-class is defined in CSS Selectors Level 4 under sound state pseudo-classes. The HTML Living Standard defines its matching behavior for media elements.

CSS Selectors Level 4 - :volume-locked

HTML Living Standard - :volume-locked