Introducing the HTML element | Blog | Chrome for Developers

✨ Check out this awesome post from Hacker News 📖

📂 **Category**:

💡 **What You’ll Learn**:

Published: June 29, 2026

Following the launch of the
element in Chrome 144, the next functional
control in the Capability Elements suite is the HTML element.
Available from Chrome 151, this element marks the next phase of the transition
from generic permission requests to targeted and functional controls for
accessing camera and microphone streams. By moving away from script-triggered
prompts toward a declarative and user-activated experience,
reduces boilerplate code, improves security, and provides a seamless recovery
path for users who have previously denied access, effectively solving the
long-standing permission hole.

From permission management to capability control

The element is the next specialized control to launch in the
Capability Elements suite, following the successful introduction of
. This transition from the original and generic
proposal—part of the PEPC initiative—lets the browser handle the unique
complexities and behaviors of different hardware capabilities more effectively.
While the early proposal focused primarily on managing permission states, such
as allow versus deny, Capability Elements function as data mediators.

The element provides a location object to your site, and
manages the entire flow for camera and microphone access. It
captures user intent, manages the browser prompt, and delivers the MediaStream
object to the application. This shift eliminates the need for separate
getUserMedia() calls, simplifies implementation, and ensures the browser has a
trusted signal of the user’s intent.

Validation of the concept

Real-world data from the initial Origin Trial demonstrated that the in-context
and user-initiated permission controls significantly improve user success rates.

Cisco observed that users who initially denied permissions were only about
10% likely to successfully grant permissions using legacy prompts, but
that rate jumped to more than 65% with the new element.
Zoom reported a 46.9% decrease in camera or microphone capture
errors, such as system-level blockers, by using the element to guide users
through recovery;
Google Meet saw a 17% decrease in “mic not working” feedback and a
131% increase in successful permission recovery for users who had
initially denied access.

Building on the patterns established by , the
element addresses the core challenges of requesting powerful capabilities. Media
requests rely on imperative JavaScript calls that often trigger out-of-context
prompts. If you accidentally block your site, reversing that decision requires
navigating deep into browser settings, a “permission hole” that often leads to
abandoned features.

The element solves these issues by providing the following:

Clear intent and timing: Because the prompt only appears after a
physical tap on a browser-controlled element, it provides a trusted signal
of intent. This lets the browser bypass automated quiet blocks that often
cause typical script-triggered requests to fail.
Simplified recovery: If access was previously denied, tapping the
element triggers a specialized recovery flow that lets you re-enable your
camera or microphone instantly on the page, without navigating complex
browser settings.
Direct stream access: As a data mediator, the element exposes the media
stream directly. This reduces the boilerplate code required to manage
callbacks and error states in your application.

Implementation

Integrating the element requires significantly less boilerplate than the legacy
JavaScript API. Following the declarative pattern established by the
element, you can add the tag to your HTML and
configure hardware requirements with the setConstraints() method.

const el = document.getElementById('media-ctrl');

// Specify hardware preferences before user interaction:
el.setConstraints(🔥);

// Handle successful stream acquisition:
el.addEventListener('stream', () => ⚡);

// Handle stream acquisition failure:
el.addEventListener('error', () => {
  console.error(`Access failed: ${el.error?.name}`);
});

// Handle prompt cancellation or dismissal:
el.addEventListener('cancel', () => {
  console.log('Permission prompt was dismissed by the user.');
});

Key attributes and properties

stream: A read-only property that provides the MediaStream object once
the user has successfully granted access.
setConstraints(): A method that lets developers update hardware
preferences, such as deviceId or resolution, prior to user interaction.
error: A read-only property that returns a DOMException (for example, a
NotAllowedError) if the request fails or is dismissed.
onstream: An event handler that fires immediately once the media tracks
are acquired.
onerror: An event handler that fires when a stream acquisition attempt
fails.
oncancel: An event handler that fires when the user cancels or dismisses
the permission prompt during acquisition.

Styling constraints

To ensure user trust and prevent deceptive design patterns, the
element applies the same strict styling restrictions as other Capability
Elements:

Legibility: The browser checks text and background colors for sufficient
contrast (at least 3:1) to ensure the request is always readable. You must
set the alpha channel (opacity) to 1 to prevent the element from being
deceptively transparent.
Sizing and spacing: The browser enforces minimum and maximum bounds for
width, height, and font-size. It disables negative margins or outline
offsets to prevent the element from being visually obscured.
Visual integrity: The browser limits distorting effects. For example,
transform supports only 2D translations and proportional scaling.
CSS pseudo-classes: The element supports state-based styling, such as
:granted (which activates once permission is active and the stream is
acquired), as well as standard interaction states like :hover and
:active.

Progressive enhancement and migration strategy

Following the design pattern established by , the
element is built to degrade gracefully. Browsers that don’t support the element
will treat it as an HTMLUnknownElement and render its children. This lets you
provide a fallback experience for all users.

Custom fallback pattern

Programmatically detect support for the element in JavaScript:

if ('HTMLUserMediaElement' in window) {
  // Use modern  element logic
} else {
  // Fallback to legacy getUserMedia() API
}

Use this detection logic to add a standard button inside the
element to trigger the legacy getUserMedia() API:

// Function for handling video/audio streams:
function handleStream (event) {
  /* ... */
}

if ('HTMLUserMediaElement' in window) {
  // In this case, we have  element support:
  const streamHandler = document.getElementById('stream-handler');

  streamHandler.addEventListener('stream', event => {
    handleStream(event);
  });
} else {
  //  element support is missing, so fall back instead:
  const fallbackStreamHandler = document.getElementById('fallback-stream-handler');

  fallbackStreamHandler.addEventListener('click', event => {
    navigator.mediaDevices.getUserMedia({video: true, audio: true}).then(handleStream);
  });
}

Migration for Origin Trial participants

For developers who integrated the experimental and generic
element during the Origin Trial, transitioning to is designed to
be minimal.

Tag update: Replace with
to ensure that all selectors targeting the previous
elements are updated to use the element
instead.
Feature detection: Update checks from HTMLPermissionElement to
HTMLUserMediaElement

The roadmap ahead

While the element handles combined audio and video requests, the
roadmap for future Capability Elements includes:

: Focuses specifically on video-only scenarios.
: Focuses specifically on audio-only scenarios.

You can see how these capability-specific elements help developers build more
intuitive and trustworthy media experiences. For more information, see the
Capability Elements technical
guide.