Availability

JavaScript 1.0; enhanced in JavaScript 1.1

Synopsis

location 
window.location 

Properties

The properties of a Location object refer to the various portions of the current document's URL. In each of the following property descriptions, the example given is a portion of this (fictitious) URL:

http://www.oreilly.com:1234/catalog/search.html?q=JavaScript&m=10#results

hash

A read/write string property that specifies the anchor portion of the URL, including the leading hash (#) mark. For example: "#result". This portion of the document URL specifies the name of an anchor within the document.

host

A read/write string property that specifies the hostname and port portions of the URL. For example, "www.oreilly.com:1234".

hostname

A read/write string property that specifies the hostname portion of a URL. For example "www.oreilly.com".

href

A read/write string property that specifies the complete text of the document's URL, unlike other Location properties which specify only portions of the URL. Setting this property to a new URL causes the browser to read and display the contents of the new URL.

pathname

A read/write string property that specifies the pathname portion of a URL. For example "/catalog/search.html".

port

A read/write string (not a number) property that specifies the port portion of a URL. For example "1234".

protocol

A read/write string property that specifies the protocol portion of a URL, including the trailing colon. For example, "http:".

search

A read/write string property that specifies the query portion of a URL, including the leading question mark. For example, "?q=JavaScript&m=10".

Methods

reload( )

Reloads the current document from the cache or the server. This method was added in JavaScript 1.1.

replace( )

Replaces the current document with a new one without generating a new entry in the browser's session history. This method was added in JavaScript 1.1.

Description

The Location object is stored in the location property of the Window object and represents the web address (the "location") of the document currently displayed in that window. The href property contains the complete URL of that document, and the other properties of the Location object each describe a portion of that URL. These properties are much like the URL properties of the Link object.

While the Link object represents a hyperlink in a document, the Location object represents the URL, or location, currently displayed by the browser. But the Location object does more than that: it also controls the location displayed by the browser. If you assign a string containing a URL to the Location object or to its href property, the web browser responds by loading the newly specified URL and displaying the document it refers to.

Instead of setting location or location.href to replace the current URL with a completely new one, you can also modify just a portion of the current URL by assigning strings to the other properties of the Location object. This creates a new URL with one new portion, which the browser loads and displays. For example, if you set the hash property of the Location object, you can cause the browser to move to a named location within the current document. Similarly, if you set the search property, you can cause the browser to reload the current URL with a new query string appended. If the URL refers to a server-side program, the document resulting from the new query string may be quite different from the original document.

In addition to its URL properties, the Location object also defines two methods. The reload( ) method reloads the current document, and the replace( ) method loads a new document without creating a new history entry for it -- the new document replaces the current one in the browser's history list.

See Also

Link, the location property of the Window object