HTML typemustmatch Attribute

Introduction

The typemustmatch attribute is used on the <object> element to ensure that an external resource’s MIME type matches the value declared in the type attribute. When present, the browser should only embed the resource if the types agree.

This helps improve security and reliability when embedding PDFs, videos, or other external files. If the server returns unexpected content (for example, HTML disguised as a PDF), strict matching can block the embed and show your fallback message instead.

What You’ll Learn

Purpose of typemustmatch

The primary purpose of the typemustmatch attribute is to enforce strict type checking for embedded resources. When this attribute is set on <object>, the browser should load the resource only if its MIME type matches the specified type attribute. This can prevent unintended or malicious content from being rendered inside the object.

Without typemustmatch, some browsers may still attempt to use a resource even when the declared type and actual content disagree. Adding the attribute makes your intent explicit.

📝 Syntax

Use typemustmatch on <object> together with data and type:

<object data="example.pdf" type="application/pdf" typemustmatch>
  <p>Your browser does not support PDFs.
    <a href="example.pdf">Download the PDF</a>.
  </p>
</object>

Syntax Rules

• Boolean attribute — presence means true; omit for default (false).
• Requires both data (resource URL) and type (expected MIME type).
• Always provide fallback content inside <object> for unsupported or blocked resources.
• JavaScript property: HTMLObjectElement.typeMustMatch (camelCase).
• Use accurate MIME types (e.g. application/pdf, video/mp4, image/svg+xml).
• Pair with Content Security Policy and trusted sources for defense in depth.

💎 Values

The typemustmatch attribute is a boolean attribute. It does not take meaningful string values:

• Present (typemustmatch or typemustmatch="") — Enforce strict MIME type matching.
• Absent — Type matching is not strictly enforced (browser default behavior).

<!-- Enforced -->
<object data="doc.pdf" type="application/pdf" typemustmatch>...</object>

<!-- Not enforced -->
<object data="doc.pdf" type="application/pdf">...</object>

Applicable Elements

typemustmatch vs type vs accept

Examples Gallery

Embed a PDF with strict matching, enable typemustmatch from JavaScript, and see fallback content when types disagree.

<object data="example.pdf" type="application/pdf" typemustmatch>
  <p>Your browser does not support PDFs.
    <a href="example.pdf">Download the PDF</a>.
  </p>
</object>

<object id="dynamicObject" data="example.pdf" type="application/pdf">
  <p>Fallback content</p>
</object>

<script>
  document.getElementById("dynamicObject").typeMustMatch = true;
</script>

<object data="report.pdf" type="video/mp4" typemustmatch>
  <p>Resource type did not match. <a href="report.pdf">Download anyway</a>.</p>
</object>

♿ Accessibility

• Always include fallback content — Provide a text description and a download link when the embed cannot load.
• Do not rely on plugins alone — Many users cannot view embedded PDFs or legacy plugin content; offer alternatives.
• Use descriptive link text — “Download the annual report (PDF)” is clearer than “click here.”
• Consider <iframe> or native viewers — For critical documents, a dedicated viewer page may be more accessible than <object>.
• Announce blocked content — Fallback messages should explain why the embed failed in plain language.

💡 Best Practices

• Use typemustmatch to enhance security by ensuring only the intended resource type is loaded.
• Combine it with other measures like Content Security Policy to further protect pages from malicious content.
• Test your implementation across different browsers to ensure consistent behavior.

🎉 Conclusion

The typemustmatch attribute is a useful feature for ensuring that embedded resources match their specified MIME types on <object> elements. By enforcing this check, you can enhance the security and reliability of your web pages.

Understanding how to use this attribute, both statically in HTML and dynamically with JavaScript, helps you control embedded content and give users clear fallback options when a resource cannot be displayed.