Specifying legacy document modes

Article
11/05/2015

In some cases, it might be necessary to restrict a webpage to a document mode supported by an older version of Windows Internet Explorer. Here we look at the x-ua-compatible header, which allows a webpage to be displayed as if it were viewed by an earlier version of the browser.

Introduction

As discussed in Defining document compatibility, <!DOCTYPE> defines the document type of a webpage, which in turn determines how the page is displayed to the end-user.

Note Starting with IE11, document modes are considered deprecated and should no longer be used. Webpages that require legacy document modes to display properly should be rewritten to use features defined by modern standards. To learn more, see Compatibility changes in IE11.

Note As of Windows 8, legacy document modes are supported only for Internet Explorer. Windows Store apps support only IE10 standards mode. For more info, see Defining document compatibility.

In most cases, we recommend that websites use the HTML5 document type to support the widest variety of established and emerging standards, as well as the broadest range of web browsers. This example shows how to specify the HTML5 document type.

<!DOCTYPE html>

Internet Explorer displays webpages that contain the HTML5 document type in standards mode, which provides the highest support available for established and emerging industry standards, including HTML5, CSS3, SVG, and others.

In some cases, existing websites might not display correctly when displayed in standards mode. This can happen for any number of reasons, including (but not limited to):

The design of a site might rely on the implementation of specific features in a specific version of a browser. In subsequent versions of the browser, that behavior has changed.
The design of a site might rely on non-standard behavior.
The design of a site might rely on functionality that's no longer supported in the latest versions of various standards or browsers.
The design of a site might rely on features defined by on an earlier version of a standard and the design of those features has either changed in later versions of the standard or has been replaced by newer standards.
The design of a site might rely on functionality that was incorrectly implemented in an earlier version of a given browser.

Regardless of the reason why a site doesn't display properly when viewed in standards mode, we recommend that you update the site to use features from the latest standards. Specific techniques depend on the specific reasons your site doesn't display correctly. For more info, see Internet Explorer 9 Compatibility Cookbook and Internet Explorer 10 Compatibility Cookbook.

Specifying legacy document modes

This next example shows how to use the x-ua-compatible header to restrict a webpage to document modes supported by an earlier version of Internet Explorer:

<html>
<head>
  <!-- Use Internet Explorer 9 Standards mode -->
  <meta http-equiv="x-ua-compatible" content="IE=9">
  <title>My webpage</title>
</head>
<body>
  <p>Content goes here.</p>
</body>
</html>

This example uses a meta element to include an X-UA-Compatible header, which directs Internet Explorer to display the webpage in IE9 Standards mode, effectively limiting the webpage to the features supported by Windows Internet Explorer 9.

The effects of the X-UA-Compatible header depend on the version of the browser used to view the webpage, as shown in the following table:

Browser version	Result	Description
Windows Store app using JavaScript or Internet Explorer in the Windows UI	IE11 EdgeHTML mode for Windows 8.1. &#;, IE10 standards mode for Windows 8.	This is the only document mode supported in these cases.
Internet Explorer for the desktop or Internet Explorer 9	IE9 Standards mode	The content attribute specifies a document mode supported by the browser.
Internet Explorer 8	IE8 Standards mode	The browser doesn't support the specified document mode, so the highest supported document mode is used instead.
Internet Explorer 7, Internet Explorer 6, or Internet Explorer 5.5 for the Mac.	IE5 (Quirks) mode	These browsers don't support the header and the webpage doesn't specify a <!DOCTYPE> directive.

When reviewing these results, keep the following points in mind:

If a webpage specifies a doctype directive and includes an X-UA-Compatible header, the header takes precedence over the directive.
If the browser supports the header, but not any of the specified document modes, it will use the highest supported document mode to display the webpage.
Older versions of the browser that don't support the header use the <!DOCTYPE> to determine the document mode.
Internet Explorer 9 and earlier versions display webpages without <!DOCTYPE> directives in IE5 (Quirks) mode. As a result, we recommend all webpages specify a <!DOCTYPE> directive, such as the HTML5 doctype.

This flexibility allows the greatest compatibility for earlier versions of Internet Explorer that remain popular. For more info, see Understanding the need for document compatibility modes.

Note Because all supported versions of Internet Explorer (including Microsoft Internet Explorer 6) interpret the HTML5 document type as a standards mode document type, we recommend using the HTML5 document type for all webpages that don't require a different declaration. This ensures that your webpages are display in the highest available standards mode.

The X-UA-Compatible header isn't case sensitive; however, it must appear in the header of the webpage (the HEAD section) before all other elements except for the title element and other meta elements.

A web server can also be configured to specify the X-UA-Compatible header. If a web server specifies the header and the header also appears within the content of a webpage, the header in the webpage takes precedence over the one specified by the server.

Note

As of IE9 mode, webpages cannot display multiple document modes. For example, consider a standards-based webpage that contains a frame element that displays content in quirks mode. IE9 mode displays the child frame in standards mode (because the parent document is in standards mode). Starting with Internet Explorer 10, however, child frames can emulate quirks mode. For more info, see IEBlog: HTML5 Quirks mode in IE10. For best results, however, use document modes consistently.

Understanding legacy document modes

When using the X-UA-Compatible header to restrict a webpage to a legacy document mode, use one of the following values:

A value corresponding to a specific document mode, such as IE9 mode, IE8 Standards mode, or IE7 Standards mode. To do so, use one of the following declarations:
- <meta http-equiv="x-ua-compatible" content="IE=9" >
- <meta http-equiv="x-ua-compatible" content="IE=8" >
- <meta http-equiv="x-ua-compatible" content="IE=7" >
By using one of these values, you're restricting the webpage to the standards mode of the corresponding version of Internet Explorer. In many cases, this means you're limiting Internet Explorer to the features supported by that version.
In certain cases, you might want Internet Explorer to use the document type declaration to either restrict a webpage to a specific standards mode or to use a document mode representing a much older version of the browser, such as Internet Explorer 5.5.

To do so, specify one of the following values, depending on your desired standards mode:
- <meta http-equiv="x-ua-compatible" content="IE=EmulateIE9" >
- <meta http-equiv="x-ua-compatible" content="IE=EmulateIE8" >
- <meta http-equiv="x-ua-compatible" content="IE=EmulateIE7" >
(This setting is useful in cases where you might have a collection of webpages that use different values for the doctype directive.)

With these settings, the page is displayed either in the standards mode corresponding to the version you specified or it's displayed in IE5 (Quirks) mode.
Use the following value to display the webpage in EdgeHTML mode, which is the highest standards mode supported by Internet Explorer, from Internet Explorer 6 through IE11.
- <meta http-equiv="x-ua-compatible" content="IE=edge" >
Note that this is functionally equivalent to using the HTML5 doctype. It places Internet Explorer into the highest supported document mode. Edge most is most useful for regularly maintained websites that are routinely tested for interoperability between multiple browsers, including Internet Explorer.

Note Starting with IE11, EdgeHTML mode is considered the preferred document mode. (In earlier versions, it was considered experimental.) To learn more, see Document modes are deprecated.

Starting with Windows Internet Explorer 8, some web developers used the EdgeHTML mode meta element to hide the Compatibility View button on the address bar. As of IE11, this is no longer necessary as the button has been removed from the address bar.

Because it forces all pages to be opened in standards mode, regardless of the version of Internet Explorer, you might be tempted to use EdgeHTML mode for all pages viewed with Internet Explorer. Don't do this, as the X-UA-Compatible header is only supported starting with Internet Explorer 8.

Tip If you want all supported versions of Internet Explorer to open your pages in standards mode, use the HTML5 document type declaration, as shown in the earlier example.
Starting with Internet Explorer 11, content values greater than "10" lead to EdgeHTML mode, which is the highest version supported by the version of Internet Explorer used to view the webpage.

The need to restrict a webpage to a legacy document mode usually occurs because the webpage is designed to support a given version of a browser or relies on older features that are no longer supported by the browser. Use legacy document modes only temporarily to allow your pages to be viewed while you update those pages to support current standards and practices.

If you decide to specify the document mode for a webpage, do so deliberately, for example:

Test the webpage in as many versions of Internet Explorer as you can, including new versions as they are released.
Set the content value of the X-UA-Compatible header to reflect the specific versions of Internet Explorer supported by your webpage, for example, the ones you've tested.
Don't set the content value to support versions of Internet Explorer that you haven't specifically tested with your webpage.

If you don't have time or resources to perform this testing, avoid setting the document mode. Only set the document mode when you have a specific business reason to do so. For more info, see When to use legacy document modes.

Determining document compatibility mode

To determine the document mode of a webpage while viewing it, use the F12 tools, as shown in Investigating document mode issues.

To determine the document compatibility mode of a webpage using JavaScript, use the documentMode property of the document object, as shown in this example.

engine = null;
if (window.navigator.appName == "Microsoft Internet Explorer")
{
   // This is an IE browser. What mode is the engine in?
   if (document.documentMode) // IE8 or later
      engine = document.documentMode;
   else // IE 5-7
   {
      engine = 5; // Assume quirks mode unless proven otherwise
      if (document.compatMode)
      {
         if (document.compatMode == "CSS1Compat")
            engine = 7; // standards mode
      }
      // There is no test for IE6 standards mode because that mode  
      // was replaced by IE7 standards mode; there is no emulation.
   }
   // the engine variable now contains the document compatibility mode.
}

The documentMode property returns a numeric value corresponding to the document mode used to display the webpage. For example, if a page is displayed in IE8 mode, documentMode returns the value 8.

The compatMode property introduced in Internet Explorer 6 is deprecated in favor of the documentMode property introduced in Internet Explorer 8. Applications that currently rely on compatMode continue to work in Internet Explorer; however, they should be updated to use documentMode.

Specifying multiple content attribute values

The content attribute of the meta element can accept multiple values. This allows you greater control over the way Internet Explorer displays your webpages; however, it increases the complexity of testing your webpage. As a result, use it sparingly and only for very specific cases.

To specify multiple document modes, set the content attribute to identify the modes you want to use. Use a comma (",") to separate each mode.

If a particular version of Windows Internet Explorer supports more than one requested document mode, it will use the highest available mode listed in the content attribute. You can use this fact to exclude specific compatibility modes, although this is not recommended. For example, the following header excludes IE8 mode.

<meta http-equiv="X-UA-Compatible" content="IE=7,9,10" >

Note The previous example is provided for illustrative purposes only; don't use it in a production environment.

The values of the content attribute are read left to right; Internet Explorer uses the highest supported value. If a webpage specifies a document compatibility mode that isn't supported by the version of Internet Explorer used to view the webpage, the webpage uses the highest version of standard mode supported by the browser. For example, if this example was viewed with Internet Explorer 8, the page would be displayed in IE7 mode. Earlier versions of the browser use the <!DOCTYPE> directive, if any, to determine how to display the webpage.

Conclusion

In general, most public websites should declare the HTML5 document type so that they are displayed in standards mode, which reflects the strongest support available to a browser for industry standards. To do so, start each of your webpages with the following line.

<!DOCTYPE html>

If, for business reasons, you decide to restrict browsers to a legacy document mode, you can use the X-UA-Compatible header to do so.

Use the F12 tools or the document.documentMode property to determine the compatibility mode of a webpage.

Specifying legacy document modes

Introduction

Specifying legacy document modes

Understanding legacy document modes

Determining document compatibility mode

Specifying multiple content attribute values

Conclusion

Additional resources