Please note, this is a STATIC archive of website developer.mozilla.org from November 2016, cach3.com does not collect or store any user information, there is no "phishing" involved.
« XUL Reference home [ Examples | Attributes | Properties | Methods | Related ]

A frame which is expected to contain a view of a Web document. It is similar to an iframe except that it holds a page history and contains additional methods to manipulate the currently displayed page.

Most of the properties and methods of the browser will rarely be used and can only be called from chrome URLs. Other URLs will need to use the document and history objects to change the displayed document.

Attributes
autocompleteenabled, autocompletepopup, autoscroll, disablehistory, disableglobalhistory, disablesecurity, droppedLinkHandler, homepage, remote,showcaret, src, type
Properties
accessibleType, canGoBack, canGoForward, contentDocument, contentPrincipal, contentTitle, contentViewerEdit, contentViewerFile, contentWindow, currentURI, docShell, documentCharsetInfo, homePage, markupDocumentViewer, messageManager, preferences, securityUI, sessionHistory, webBrowserFind, webNavigation, webProgress
Methods
addProgressListener, goBack, goForward, goHome, gotoIndex, loadURI, loadURIWithFlags, reload, reloadWithFlags, removeProgressListener, stop, swapDocShells

Examples

Image:XUL_ref_browser.png
<!-- shows Mozilla homepage inside a groupbox -->
<groupbox flex="1">
  <caption label="Mozilla homepage"/>
  <browser type="content" src="https://www.mozilla.org" flex="1"/>
</groupbox>

Attributes

autocompleteenabled
Type: boolean
Set to true to enable autocomplete of fields.
autocompletepopup
Type: id
The id of a popup element used to hold autocomplete results for the element.
autoscroll
Type: boolean
Set to false to disable autoscroll for this browser. If this attribute is set to true or omitted, autoscroll will be enabled or depending on the user preference general.autoScroll.
disablehistory
Type: boolean
Disables both session and global history for the docshell attached to the browser.
disableglobalhistory
Type: boolean
Disables global history for the docshell attached to the browser while keeping session history active.
disablesecurity
Type: boolean
Set this attribute to true to disable the security UI for this browser. Omit this attribute off to enable it.
droppedLinkHandler
Type: function
Function that is called when links are dropped to the browser element, with the following arguments. 
droppedLinkHandler(event, uri, name) -- Firefox 51 or older
droppedLinkHandler(event, links) -- Firefox 52 or newer
  • event -- drop event, or null if no event is available
  • uri -- uri of the dropped link
  • name -- name of the dropped link
  • links -- array of the dropped items with nsIDroppedLinkItem interface
homepage
Type: URL
This attribute allows you to set a homepage for the browser element. It does not have any correlation with the user's browser homepage; instead it is a convenient property to hold a home page. You can switch to this home page using the goHome method.
remote
Type: Boolean
If true, the content of the XUL <browser> will be processed inside its own process. The document is then accessible from the chrome content only through the message manager.
showcaret
Type: boolean
Whether or not to cause a typing caret to be visible in the content area. Default is false.
src
Type: URI
The URI of the content to appear in the element.
type
Type: one of the values below
The type of browser, which can be used to set the access of the document loaded inside the browser. If this is not set, the loaded document has the same access as the window containing the browser. More precisely: The document loaded into a chrome window is always of chrome type. Subdocuments of chrome documents are of chrome type unless the container element (one of iframe, browser or editor) has one of the special type attribute values (the common ones are content, content-targetable and content-primary) indicating that the subdocument is of content type. This boundary has a number of special effects such has making window.top == window (unless the browser is added to a chrome document) and preventing documents from inheriting the principal of the parent document. The type attribute on all frames in content documents is ignored; subdocuments of content documents are always content documents.
Warning: The type attribute must be set before the element is inserted into the document.
content
A browser for content. The content that is loaded inside the browser is not allowed to access the chrome above it.
content-primary
The primary browser for content. The content that is loaded inside the browser is not allowed to access the chrome above it. For instance, in a web browser, this would be the element that displays the web page. The window for the primary content can be retrieved more conveniently using window.content.
content-targetable
One browser among many for content. The content that is loaded inside the browser is not allowed to access the chrome above it. This is the preferred value for any browser element in an application that will use multiple browsers of equal privileges and is unselected at the moment.
chrome
(default behaviour): A browser, intended to be used for loading privileged content using a chrome:// URI. Don't use for content from web, as this may cause serious security problems!

Properties

accessibleType
Type: integer
A value indicating the type of accessibility object for the element.
canGoBack
Type: boolean
This read-only property is true if there is a page to go back to in the session history and the Back button should be enabled.
canGoForward
Type: boolean
This read-only property is true if there is a page to go forward to in the session history and the Forward button should be enabled.
contentDocument
Type: document
This read-only property contains the document object in the element.
contentPrincipal
Type: nsIPrincipal
This read-only property contains the principal for the content loaded in the browser, which provides security context information.
contentTitle
Type: string
This read-only property contains the title of the document object in the browser.
contentViewerEdit
Type: nsIContentViewerEdit
This read-only property contains the nsIContentViewerEdit which handles clipboard operations on the document.
contentViewerFile
Type: nsIContentViewerFile
Reference to the nsIContentViewerFile interface for the document.
contentWindow
Type: TODO
Use the contentWindow.wrappedJSObject to obtain a DOM(html) window object
currentURI
Type: nsIURI
This read-only property contains the currently loaded URL. To change the URL, use the loadURI method.
docShell
Type: nsIDocShell
This read-only property contains the nsIDocShell object for the document.
documentCharsetInfo Obsolete since Gecko 12.0
Type: nsIDocumentCharsetInfo
This read-only property contains the nsIDocumentCharsetInfo object for the document which is used to handle which character set should be used to display the document. The properties of the nsIDocumentCharsetInfo object were merged into the docshell in Gecko 12.0 (Firefox 12.0 / Thunderbird 12.0 / SeaMonkey 2.9).
homePage
Type: string home page URL
This property holds the value of the user's home page setting.
markupDocumentViewer
Type: nsIMarkupDocumentViewer
This read-only property contains the nsIMarkupDocumentViewer which is responsible for drawing the document.
messageManager
Type: message manager object
This read-only property returns the message manager object for the browser element.
preferences
Type: nsIPrefService
This read-only property contains an nsIPref object for getting and setting user preferences.
securityUI
Type: nsISecureBrowserUI
The read-only property holds an object which may be used to determine the security level of the loaded document.
sessionHistory
Type: nsISHistory
This read-only property contains the nsISHistory object which holds the session history.
webBrowserFind
Type: nsIWebBrowserFind
This read-only property contains an nsIWebBrowserFind object which can be used to search for text in the document.
webNavigation
Type: nsIWebNavigation
This read-only property contains the nsIWebNavigation object for the document. Most of its methods are callable directly on the element itself, such as goBack and goForward. It also contains the load constants used by reloadWithFlags and loadURIWithFlags.
webProgress
Type: nsIWebProgress
This read-only property contains an nsIWebProgress object which is used to monitor the progress of a document loading.

Methods

Inherited Methods
addEventListener(), appendChild(), blur, click, cloneNode(), compareDocumentPosition, dispatchEvent(), doCommand, focus, getAttribute(), getAttributeNode(), getAttributeNodeNS(), getAttributeNS(), getBoundingClientRect(), getClientRects(), getElementsByAttribute, getElementsByAttributeNS, getElementsByClassName(), getElementsByTagName(), getElementsByTagNameNS(), getFeature(), getUserData, hasAttribute(), hasAttributeNS(), hasAttributes(), hasChildNodes(), insertBefore(), isDefaultNamespace(), isEqualNode, isSameNode, isSupported(), lookupNamespaceURI, lookupPrefix, normalize(), querySelector(), querySelectorAll(), removeAttribute(), removeAttributeNode(), removeAttributeNS(), removeChild(), removeEventListener(), replaceChild(), setAttribute(), setAttributeNode(), setAttributeNodeNS(), setAttributeNS(), setUserData

addProgressListener( listener )
Return type: no return value
Add a progress listener to the browser which will monitor loaded documents. The progress listener should implement the nsIWebProgressListener interface.
goBack()
Return type: no return value
Go back one page in the history.
goForward()
Return type: no return value
Go forward one page in the history.
goHome()
Return type: no return value
Load the user's home page into the browser.
gotoIndex( index )
Return type: no return value
Navigate to the page in the history with the given index. Use a positive number to go forward and a negative number to go back.

NOTE: This is the XUL method on <browser> / <tabbrowser>, not the global function in chrome://browser/content/browser.js. Please check which one you're documenting! (This one has no post data parameter, see loadURIWithFlags for a version that does)

loadURI( uri, referrer, charset )
Return type: no return value
Load a URL into the document, with the given referrer and character set.
The first argument should be a string, not a nsIURI object. To get a string from an nsIURI, use nsIURI.spec or nsIURI.asciiSpec
loadURIWithFlags( uri, flags, referrer, charset, postData )
Return type: no return value
Load a URL into the document, with the specified load flags, the given referrer, character set, and POST data. In addition to the flags allowed for the reloadWithFlags method, the following flags are also valid:
  • LOAD_FLAGS_IS_REFRESH: This flag is used when the URL is loaded because of a meta tag refresh or redirect.
  • LOAD_FLAGS_IS_LINK: This flag is used when the URL is loaded because a user clicked on a link. The HTTP Referer header is set accordingly.
  • LOAD_FLAGS_BYPASS_HISTORY: Do not add the URL to the session history.
  • LOAD_FLAGS_REPLACE_HISTORY: Replace the current URL in the session history with a new one. This flag might be used for a redirect.

(See nsIWebNavigation.loadURI() for details on the referrer and postData parameters.)

reload()
Return type: no return value
Reloads the document in the browser element on which you call this method.
reloadWithFlags( flags )
Return type: no return value
Reloads the document in the browser with the given load flags. The flags listed below may be used, which are all constants of the webNavigation property (or the nsIWebNavigation interface). You may combine flags using a or symbol ( | ).
  • LOAD_FLAGS_NONE: No special flags. The document is loaded normally.
  • LOAD_FLAGS_BYPASS_CACHE: Reload the page, ignoring if it is already in the cache. This is the flag used when the reload button is pressed while the Shift key is held down.
  • LOAD_FLAGS_BYPASS_PROXY: Reload the page, ignoring the proxy server.
  • LOAD_FLAGS_CHARSET_CHANGE: This flag is used if the document needs to be reloaded because the character set changed.
removeProgressListener( listener )
Return type: no return value
Remove a nsIWebProgressListener from the browser.
stop()
Return type: no return value
Equivalent to pressing the Stop button, this method stops the currently loading document.
swapDocShells( otherBrowser )
Return type: no return value
Swaps the content, history and current state of this browser with another browser. During the swap, pagehide and pageshow events are fired on both browsers. This method can be used to move browser between windows or tear off a browser into a new window.

Note: Both browsers must be either standalone browsers or embedded in a tabbrowser. You can't mix them.

Interfaces
nsIAccessibleProvider

Document Tags and Contributors

Tags: 
 Contributors to this page: arai, ato, Sheppy, Laurentj, mhammond, trevorh, MarkFinkle, Johnjbarton, Marsf, Enn, Nickolay, 3dkiwi, Mgjbot, Ptak82, Callek, Cozby, Dria, Pmash
 Last updated by: arai,