IE8 browser mode vs document mode

Browser Mode: Specifies the user agent sent by the browser to the Web Server. Rendering differences can occur if your JavaScript or back-end code renders differently based on the user agent string. For example, you may see JavaScript that checks navigator.userAgent. (Mozilla/5.0 (compatible; MSIE 8.0...) This value is also used to to process conditional comments ([if lte IE 9], [if gt IE 8], etc.). The Emulation tooling in IE 11 does not have a browser mode. It has a user agent drop-down instead.

Document Mode: Specifies the rendering engine used to process the markup. This is typically where we see rendering issues and browser incompatibilities. The original goal (for better or worse) was website owners could choose a document mode for their site via a meta tag. In IE 11, the emulation tools are less confusing.

Testing: If your goal is to emulate an old IE8 browser, you should change both browser mode and document mode. The emulation is not perfect, so a more thorough option is to download free test VMs from Microsoft where you can test with a *real" version of IE 8, 9, etc.

What causes these values to change?

The Browser mode will not change. (Unless you change it in Dev tools.) It is set before making the request to the web server.

The document mode can change based on web server response. It can be changed via a X-UA-Compatible HTTP response header, the doc type, meta tags, Intranet sites, markup issues, etc.


From this article on the IE8 blog, entitled How IE8 Determines Document Mode

  1. The Developer Tools settings override all Document Modes for pages displayed in a tab.
  2. The X-UA-Compatible meta tag and then header override Compatibility View Settings and the doctype unless the X-UA-Compatible value is EmulateIE7 or EmulateIE8.
  3. The user’s Compatibility View Settings override the Microsoft Compatibility View List.
  4. If none of the above rules apply, the doctype determines whether the webpage renders in IE8 Standards, IE8 Almost Standards or Quirks Mode.

So from that we get the following answers to your questions:

Q. What is the difference between browser mode and document mode in simple terms?
A. Browser mode is set in the developer tools to emulate different IE browser version behaviors while document mode is defined on the web page to tell IE to render the site differently for compatibility purposes.

Q. What causes the browser mode to change?
A. The user changes the browser mode in the dev tools.

Q. What causes the document mode to change?
A. The Doctype and the X-UA-Compatible meta tag and header set by the web developer.

Q. If a user changes the mode(s) via developer tools, does the change remain even if the page is refreshed?
A. The Browser Mode will stay, but if you change the Doctype and X-UA-Compatible, they will go back to what is defined on the page.

UPDATE: As Adrien Be points out below, IE9+ adds the ability to change the document mode in the dev tools via a setting which will persist on refresh.


See your answer in this page.

The documentMode property returns the mode used by the browser to render the current document.

IE8 can render a page in different modes, depending on the !DOCTYPE or the presence of certain HTML elements.

This property returns one of following values:

5 - The page is displayed in IE5 mode
7 - The page is displayed in IE7 mode
8 - The page is displayed in IE8 mode
9 - The page is displayed in IE9 mode

Note: If no !DOCTYPE is specified, IE8 renders the page in IE5 mode!

Diagram of the document mode selection process