Defining Document Compatibility
[This documentation is preliminary and is subject to change.]
Updated: March 2011
Document compatibility defines how Windows Internet Explorer renders your webpages. This article explains document compatibility, how to specify the document compatibility mode for your webpages, and how to determine the document mode of a webpage.
- Introduction
- Understanding the Need for Document Compatibility
- Specifying Document Compatibility Modes
- Understanding Document Compatibility Modes
- When to Use Document Compatibility Modes
- Configuring Web Servers to Specify Default Compatibility Modes
- Determining Document Compatibility Mode
- Understanding Content Attribute Values
- Controlling Default Rendering
- Conclusion
- Related topics
Introduction
In most cases, we recommend that websites use the HTML5 document type in order to support the widest variety of established and emerging standards, as well as the broadest range of web browsers. The following example shows how to specify the HTML5 document type.
<!DOCTYPE html>
Windows Internet Explorer 9 displays webpages that contain the HTML5 document type in IE9 Standards mode, which provides the highest support available for established and emerging industry standards, including the HTML5 (Working Draft), W3C Cascading Style Sheets Level 3 Specification (Working Draft), Scalable Vector Graphics (SVG) 1.0 Specification, and others.
In some cases, existing websites may not display correctly when displayed in IE9 mode. This can happen for any number of reasons, including (but not limited to) the following:
-
The design of a site may rely on the behavior of a specific version of a browser and that behavior has changed in later versions of the browser, such as conditional comments, version vectors, and user-agent detection.
-
The design of a site may rely on non-standard behavior.
-
The design of a site may rely on functionality that is no longer supported in the latest versions of various standards or browsers.
-
The design of a site may rely on functionality that was incorrectly implemented in an earlier version of a given browser.
Regardless of the reason why a site does not display properly when viewed in IE9 mode, we recommend that you update the site to use techniques that incorporate features from the latest standards. Specific techniques will depend on the specific reasons your site does not display correctly. For more information, please see Internet Explorer 9 Compatibility Cookbook.
To help ensure that your sites are available while you redesign them, Internet Explorer 9 supports document compatibility, which refers to a set of features that allow you to direct Internet Explorer 9 to display your pages as if they were viewed by older versions of the browser.
Document compatibility controls the features that are supported by webpages and the way webpages are displayed in the browser. An extension of the compatibility mode introduced in Microsoft Internet Explorer 6, document compatibility enables you to choose the specific rendering mode that Windows Internet Explorer uses to display your webpages.
This article describes the historical need for document compatibility, lists the document compatibility modes available to recent versions of Internet Explorer, and shows how to select specific compatibility modes.
Understanding the Need for Document Compatibility
Each major release of Internet Explorer adds features designed to make the browser easier to use, to increase security, and to more closely support industry standards. As Internet Explorer gains features, there is a risk that older websites may not display correctly.
To minimize this risk, Internet Explorer 6 allowed web developers to choose the way Internet Explorer interpreted and displayed their webpages. "Quirks mode" was the default; it displayed pages as if they were viewed with older versions of the browser. "Standards mode" (also known as "strict mode") featured the most support for industry standards; however, to take advantage of this enhanced support, webpages needed to include an appropriate <!DOCTYPE> directive.
If a site did not include a <!DOCTYPE> directive, Internet Explorer 6 would display the site in quirks mode. If a site contained a valid <!DOCTYPE> directive that the browser did not recognize, Internet Explorer 6 would display the site in Internet Explorer 6 standards mode. Because few sites already included the <!DOCTYPE> directive, the compatibility mode switch was highly successful. It allowed Web developers to choose the best time to migrate their sites to standards mode.
Over time, many sites began to rely on standards mode. They also began to use the features and behavior of Internet Explorer 6 to detect Internet Explorer. For example, Internet Explorer 6 did not support the universal selector; some web sites used this as a way to serve specific content to Internet Explorer.
Windows Internet Explorer 7 offered new features that were designed to more fully support industry standards, such as support for the universal selector. Because the <!DOCTYPE> directive only supports two settings (quirks mode and standards mode), IE7 Standards mode replaced Internet Explorer 6 standards mode.
As a result, sites that relied on the behavior of Internet Explorer 6 standards mode (such as lack of support for the universal selector) failed to detect the new version of the browser. This meant that content intended for Internet Explorer was not served to Internet Explorer 7, which in turn caused these sites to not display as intended. Because Internet Explorer 7 only supported two compatibility modes, the owners of affected sites were forced to update their sites to support IE7 mode in order for people to view them using Internet Explorer 7.
Windows Internet Explorer 8 added support for selected features from emerging standards, which are standards that have not yet been finalized. Because the behavior of some features varied from previously published standards, it became necessary to allow web developers to choose which standards were supported by their webpages. Internet Explorer 8 introduced the concept of document compatibility, which lets you specify the version (or versions) of Internet Explorer that your site is designed to support. Document compatibility added new modes to Internet Explorer 8, such as IE8 Standards mode.
Internet Explorer 9 more fully supports emerging standards, such as HTML5, Cascading Style Sheets, Level 3 (CSS3), Scalable Vector Graphics (SVG) 1.1 (Second Edition), and others. Because the standards are still being developed, certain behavior has changed and Internet Explorer 9 supports the latest behavior specified in these standards as of the time of publication. As you might expect, these features are only available for webpages displayed in IE9 mode.
If your site does not display correctly in Internet Explorer, you can either update the site to support the latest web standards (preferred) or you can force Internet Explorer to display your content as if it were being viewed in an older version of the browser. This is done by using the meta element to add an X-UA-Compatible header to your webpages.
This allows you to choose when to update your site to support new features supported by Internet Explorer.
Specifying Document Compatibility Modes
Document compatibility modes allow you to control the way Internet Explorer interprets and displays your webpage. To specify a specific document mode for your webpage, use the meta element to include an X-UA-Compatible header in your webpage. The following example specifies EmulateIE7 mode.
<html> <head> <!-- Mimic Internet Explorer 7 --> <meta http-equiv="X-UA-Compatible" content="IE=EmulateIE7" > <title>My webpage</title> </head> <body> <p>Content goes here.</p> </body> </html>
In this example, the X-UA-Compatible header directs Internet Explorer to mimic the behavior of Internet Explorer 7 when determining how to display the webpage. This means that Internet Explorer will use the <!DOCTYPE> directive (or lack thereof) to choose the appropriate document type. Since this page does not contain a <!DOCTYPE> directive, the example would be displayed in IE5 (Quirks) mode.
The content attribute specifies the mode for the page; to mimic the behavior of Internet Explorer 7, specify IE=EmulateIE7. Specify IE=5, IE=7, IE=8 or IE=9 to select one of those compatibility modes. You can also specify IE=edge to tell Internet Explorer to use the highest mode available.
The following section describes supported document compatibility modes in more detail.
The X-UA-Compatible header is not 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.
Understanding Document Compatibility Modes
Internet Explorer supports a number of document compatibility modes that enable different features and can affect the way content is displayed:
-
IE9 mode provides the highest support available for established and emerging industry standards, including the HTML5 (Working Draft), W3C Cascading Style Sheets Level 3 Specification (Working Draft), Scalable Vector Graphics (SVG) 1.0 Specification, and others.
-
IE8 mode supports many established standards, including the W3C Cascading Style Sheets Level 2.1 Specification and the W3C Selectors API; it also provides limited support for the W3C Cascading Style Sheets Level 3 Specification (Working Draft) and other emerging standards.
-
IE7 mode renders content as if it were displayed in standards mode by Internet Explorer 7, whether or not the page contains a <!DOCTYPE> directive.
-
Emulate IE9 mode tells Internet Explorer to use the <!DOCTYPE> directive to determine how to render content. Standards mode directives are displayed in IE9 mode and quirks mode directives are displayed in IE5 mode. Unlike IE9 mode, Emulate IE9 mode respects the <!DOCTYPE> directive.
-
Emulate IE8 mode tells Internet Explorer to use the <!DOCTYPE> directive to determine how to render content. Standards mode directives are displayed in IE8 mode and quirks mode directives are displayed in IE5 mode. Unlike IE8 mode, Emulate IE8 mode respects the <!DOCTYPE> directive.
-
Emulate IE7 mode tells Internet Explorer to use the <!DOCTYPE> directive to determine how to render content. Standards mode directives are displayed in Internet Explorer 7 standards mode and quirks mode directives are displayed in IE5 mode. Unlike IE7 mode, Emulate IE7 mode respects the <!DOCTYPE> directive. For many web sites, this is the preferred compatibility mode.
-
IE5 mode renders content as if it were displayed in quirks mode by Internet Explorer 7, which is very similar to the way content was displayed in Microsoft Internet Explorer 5.
-
Edge mode tells Internet Explorer to display content in the highest mode available. With Internet Explorer 9, this is equivalent to IE9 mode. If a (hypothetical) future release of Internet Explorer supported a higher compatibility mode, pages set to edge mode would appear in the highest mode supported by that version. Those same pages would still appear in IE9 mode when viewed with Internet Explorer 9.
Because edge mode documents display webpages using the highest mode available to the version of Internet Explorer used to view them, it is recommended that you should only use this document mode for testing purposes only. Do not use it for production uses.
When to Use Document Compatibility Modes
In many cases, it's best to use the <!DOCTYPE> directive to specify a standards-based document type, such as the HTML5 document type shown in the following example.
<!DOCTYPE html>
This allows your site take advantage of developments and feature enhancements made to web browsers as new versions are released.
However, there are situations where it is appropriate to use document compatibility to display your webpages as if they were viewed in an older version of Internet Explorer. The following list shows a few different examples:
-
If you are creating an application designed to be viewed by a single computer or web browser, such as a multimedia presentation displayed in a kiosk, it may be appropriate to use the
X-UA-Compatibleheader to ensure that the application is displayed consistently, even after updating the hardware or software that powers the kiosk. -
If you have created a custom application that is accessed through an Intranet environment, such as a line-of-business (LOB) application developed for a company's internal use, the
X-UA-Compatibleheader can help you reduce the maintenance required to support the application through future operating system upgrades or future browser updates. -
If you are archiving web content and plan to have that available on an as-is basis, that is, the archived content will not be actively maintained, the
X-UA-Compatibleheader can help ensure that it will be presented as originally intended. -
If your website uses a content management software (CMS) solution or other framework and you do not have direct control over the server or the document type used for your webpage, the
X-UA-Compatibleheader may allow you to control the document mode that Internet Explorer uses to display your webpage. (This depends on the underlying design of the site.)
If, however, you are creating a public website, one that might be viewed by a variety of web browsers and users, you should design your site so it uses a standards-based document types, such as the HTML5 declaration shown in the following example.
<!DOCTYPE html>
This helps ensure that your site is displayed as consistently as possible when viewed by different browsers; it also helps ensure that the appearance of your site adapts to changes in the specifications underlying the standards that your site relies on.
If your site does not currently display properly when viewed by Internet Explorer 9, you can use the X-UA-Compatible header to make your site available while you redesign it so that it displays properly when viewed in IE9 standards mode. This should be a temporary measure, one that is removed when your site more fully supports standards-based document types.
Ultimately, the document compatibility decision is a design decision, one that you can only make after carefully weighing the various factors involved.
Configuring Web Servers to Specify Default Compatibility Modes
Site administrators can configure their sites to default to a specific document compatibility mode by defining a custom header for the site. The specific process depends on your Web server. For example, the following web.config file enables Microsoft Internet Information Services (IIS) to define a custom header that automatically renders all pages in IE7 mode.
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<system.webServer>
<httpProtocol>
<customHeaders>
<clear />
<add name="X-UA-Compatible" value="IE=7" />
</customHeaders>
</httpProtocol>
</system.webServer>
</configuration>
If you specify a default document compatibility mode using your web server, you can override that setting by specifying a different document compatibility mode in a specific webpage. The mode specified within the webpage takes precedence over the mode specified by the server.
Consult the documentation of your particular web server for information on specifying custom headers. For more information, see:
Determining Document Compatibility Mode
To determine the document compatibility mode of a webpage using Internet Explorer, use the documentMode property of the document object. For example, typing the following into Internet Explorer address bar displays the document mode for the current webpage.
javascript:alert(document.documentMode);
The documentMode property returns a numeric value corresponding to the document compatibility mode used to display the webpage. For example, if a page has chosen to support 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 8; however, they should be updated to use documentMode.
If you want to use JavaScript to determine the document compatibility mode of a webpage, use care to support older versions of Internet Explorer, as shown in the following 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.
}
Understanding Content Attribute Values
The content attribute of the META element is flexible in that it accepts values other than the ones described previously. This allows you greater control over the way Internet Explorer displays your webpages. For example, you can set the content attribute to IE=7.5. When you do this, Internet Explorer attempts to convert the value to a version vector and selects the mode closest to that result. In this case, Internet Explorer would be set to IE7 mode. The following examples show the modes selected for other values when there are no other mitigating factors.
<meta http-equiv="X-UA-Compatible" content="IE=4"> <!-- IE5 mode -->
<meta http-equiv="X-UA-Compatible" content="IE=7.5" > <!-- IE7 mode -->
<meta http-equiv="X-UA-Compatible" content="IE=100" > <!-- IE9 mode -->
<meta http-equiv="X-UA-Compatible" content="IE=a" > <!-- IE5 mode -->
<!-- This header mimics Internet Explorer 7 and uses
<!DOCTYPE> to determine how to display the webpage -->
<meta http-equiv="X-UA-Compatible" content="IE=EmulateIE7" >
Note The previous example shows the results of individual content values. In practice, Internet Explorer respects only the first X-UA-Compatible header in a webpage.
You can also use the content attribute to specify multiple document compatibility modes. To specify multiple document modes, set the content attribute to identify the modes you want to use. Use a semicolon to separate each mode.
If a particular version of Internet Explorer supports more than one requested compatibility 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 IE7 mode.
<meta http-equiv="X-UA-Compatible" content="IE=9; IE=8; IE=5" >
Note The previous example is provided for illustrative purposes only; it should not be used in a production environment.
If a webpage specifies a document compatibility mode that is not supported by the version of Internet Explorer used to view the webpage, the webpage will be displayed in the highest document mode supported by that version of Internet Explorer. For example, a page that specifies IE9 mode will be displayed in IE8 mode when viewed by Internet Explorer 8. Earlier versions of the browser will use the <!DOCTYPE> directive, if any, to determine how to display the webpage.
Controlling Default Rendering
Internet Explorer 8 and later. When Internet Explorer encounters a webpage that does not contain an X-UA-Compatible header, it uses the <!DOCTYPE> directive to determine how to display the page.
If the <!DOCTYPE> directive specifies a standards-based document type, Internet Explorer displays the page in IE9 mode. The HTML5 document type is a standards-based document type and is declared as shown in the following example.
<!DOCTYPE html>
If the <!DOCTYPE> directive is missing or does not specify a standards-based document type, Internet Explorer displays the page in IE5 mode.
Be aware that certain conditions can force Internet Explorer to display pages in a document compatibility mode different from the one specified in the webpage. This includes, but is not limited to, the following situations:
-
Compatibility View is enabled for the page.
-
The page is loaded in the Intranet zone and Internet Explorer is configured to use Compatibility View for pages loaded from the Interanet zone.
-
Internet Explorer is configured to display all web sites in Compatibility View.
-
Internet Explorer is configured to use the Compatibility View List, which specifies a set of web sites that are always displayed in Compatibility View.
-
The Developer Tools are used to override the settings specified in the webpage.
-
The webpage encountered a page layout error and Internet Explorer is configured to automatically recover from such errors by reopening the page in Compatibility View.
The following links provide additional information describing how Internet Explorer determines the appropriate document mode for a webpage"
- Internet Explorer Blog: Compatiblity Features for Site Developers
- Internet Explorer Blog: Compatibility View Recap
- Internet Explorer Standards Support Overview, Section 2.1.2: Document Modes
Note When configured to load intranet pages in Compatibility View, Internet Explorer makes an exception for pages loaded using the localhost address or a loopback address. Pages loaded using one of these techniques are displayed in standards mode when the <!DOCTYPE> directive specifies a standards-based document type.
In addition, Internet Explorer supports a feature control that allows you to control the way the browser handles webpages that do not contain X-UA-Compatible headers. For more information, please see the Browser Emulation feature control.
Conclusion
Most websites should declare the HTML5 document type so that they are displayed correctly when viewed by browsers that support the latest versions of established and emerging standards. To do so, start each of your webpages with the following line.
<!DOCTYPE html>
For a small number of existing websites, compatibility may be an important consideration. While it is strongly recommended that you create sites that do not rely on specific behaviors or features of a web browser, there are times when this is not immediately feasible. You can use the X-UA-Compatible header to direct Internet Explorer to display a webpage as if it were being viewed by an older version of the browser.
Use the X-UA-Compatible header to specify the versions of Internet Explorer that your pages support. Use document.documentMode to determine the compatibility mode of a webpage.
By choosing to support a specific version of Internet Explorer, you can help ensure that your users will be able to view your pages while you resolve the issues that prevent your sites from displaying properly when viewed with browsers that support the latest versions of established and emerging standards.
Related topics
- documentMode
- compatMode
- doctype
- CSS Enhancements in Internet Explorer 6
- About Conditional Comments
Build date: 2/14/2012
The HTML 5 spec says:
Note item 2: Any number of comments and space characters.Documents must consist of the following parts, in the given order:
- Optionally, a single "BOM" (U+FEFF) character.
- Any number of comments and space characters.
- A DOCTYPE.
- Any number of comments and space characters.
- The root element, in the form of an
htmlelement.- Any number of comments and space characters.
The problem with IE9 is that if there are any comments before the DOCTYPE IE9 renders the document in quirks mode instead of compatibility mode, even though it is a fully HTML 5 compliant document. It must be a bug: if it were a feature it would be documented on this page.
Hope this helps save time for others...
- 5/11/2012
- sahack
<meta http-equiv="X-UA-Compatible" content="IE=edge" >
Would ensure a higher compatibility mode - except it does not work. I have tried different values for IE to no avail - I stil cannot get the page to render correctly on my local environment.
Trying to see the sense in why this has been done like this? Unfortunately, I don't have an answer yet for others who might be experiencing a similar problem.
- 5/7/2012
- Jrhansen
- 3/7/2012
- _bug_
- 1/27/2012
- gmorris_timecentre
- 1/27/2012
- gmorris_timecentre
Such as <meta http-equiv="X-UA-Compatible" content="IE=EmulateIE8" >
Thanks!
- 10/5/2011
- andyssundaypink
- 11/15/2011
- lingvomir
- 9/13/2011
- gigun
....BhabuSri.....
- 8/27/2011
- BhanuSri
<meta http-equiv="X-UA-Compatible" content="IE=EmulateIE7" > <!-- IE7 mode -->
but this does::
<meta http-equiv="X-UA-Compatible" content="IE=7.5" > <!-- IE7 mode -->
and im using internet exlorer 8
---------------------
check this out httP://www.lipfeed.com
- 5/21/2011
- got2
The above states an example of specifying *multiple* document modes, typically to exclude one particular document mode; or, to put it differently, skip an IE version:
<meta http-equiv="X-UA-Compatible" content="IE=9; IE=8; IE=5" >
However, after trial and error, I've found that the above does NOT work, and must instead be specified as follows:
<meta http-equiv="X-UA-Compatible" content="IE=5,8,9" >
Note:
- only 1 "IE" token, with versions separated by commas, not semicolons
- version numbers are in *ascending* order.
- 5/16/2011
- mklement1
- 3/4/2011
- jakeEatsHisPeas
What are the new values with IE9?
9000 = IE9 mode.
Is 9888 or 9999 the 'always display in IE9 mode'.
sabbir hasan.
- 9/20/2010
- Mark AJA
- 1/31/2011
- sabbir hasan
What are the new values with IE9?
9000 = IE9 mode.
Is 9888 or 9999 the 'always display in IE9 mode'.
- 9/20/2010
- Mark AJA
- 9/7/2010
- Jason.Chiu
http://blogs.msdn.com/giorgio/archive/2009/04/14/how-to-detect-ie8-using-javascript-client-side.aspx
- 6/18/2009
- Giorgio Sardo [MSFT]
- 6/7/2010
- Thomas Lee
- 3/16/2010
- joselitocr
- 6/7/2010
- Thomas Lee
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head><title>
Untitled Page
</title></head>
No meta tag... any resolution for getting this to apply machine-wide?
- 5/27/2010
- D Vozel
protected void Page_PreRender(object sender, EventArgs e)
{
HtmlMeta metatag = new HtmlMeta();
metatag.Attributes.Add("http-equiv", "X-UA-Compatible");
metatag.Attributes.Add("content", "ID=EmulateIE7");
Page.Header.Controls.AddAt(0,metatag);
}
Hope this helps.
- 4/19/2010
- IsaacDiaz
- 4/11/2009
- cheyennemtnman
- 3/28/2009
- Φ
- 3/20/2009
- dhmderuiter
What is IE8's default behavior, if you do not specify the meta tag?
In beta2 it seems, it still gets my plain old doctype and switches to 'quirks mode', which implicates IE8Emulate mode, if I understand it correctly?
- 1/5/2009
- Webmaster J
- 10/25/2008
- Cowboy_X
- 8/25/2008
- ChrisMahoney
"If a site did not include a <!DOCTYPE> directive, Internet Explorer 6 would display the site in quirks mode. If a site contained a valid <!DOCTYPE> directive that the browser did not recognize, Internet Explorer 6 would display the site in Internet Explorer 6 standards mode."
Do you mean:
"If a site did not include a <!DOCTYPE> directive, Internet Explorer 6 would display the site in quirks mode. If a site contained a valid <!DOCTYPE> directive that the browser did recognize, Internet Explorer 6 would display the site in Internet Explorer 6 standards mode."
see http://msdn.microsoft.com/en-us/library/bb250395.aspx
- 6/23/2008
- Michał Morciniec
- 6/24/2008
- Michał Morciniec