[Chapter 21] Reference: Document.write()
Author: David Flanagan
Date: Fri Aug 29 11:15:20 1997

#

| Chapter 21 JavaScript Reference |

# Document.write() Method

## Name

Document.write() Method---append data to a document

## Availability

Navigator 2.0, Internet Explorer 3.0

## Synopsis

    document.write(value,...)

### Arguments

`value`

  An arbitrary JavaScript value that is to be appended to `document`. If the value is not a string, it is converted to one before being appended.

`...`

  Any number (zero or more) of additional values to be appended (in order) to `document`.

### Returns

nothing

## Description

`document``.write()` appends each of its arguments, in order, to `document`. String values are appended as is. Numeric values are converted to a string representation, and Boolean values are appended as either the string "true" or the string "false". Object values are converted to strings by invoking their `toString()` method.

`Document.write()` is usually used in one of two ways. The first is when it is invoked on the current document within a `<SCRIPT>` tag or within a function that is executed while the document is still being parsed. In this case, the `write()` method writes its HTML output as if that output appeared literally in the file, at the location of the code that invoked the method.

The second way that `Document.write()` is commonly used is to dynamically generate the contents of documents other than that of the current window. In this case, the target document is never in the process of being parsed, and so the output cannot appear "in place" as it does in the case described above. In order for `write()` to output text into a document, that document must be "open." You can open a document by explicitly calling the `Document.open()` method, if you choose. In most cases this is unnecessary, however, because when `write()` is invoked on a document that is "closed," it implicitly opens the document. When a document is opened, any contents that previously appeared in that document are discarded and replaced with a blank document.

Once a document is open, `Document.write()` can append any amount of output to the end of the document. When a new document has been completely generated by this technique, the document should be closed by calling `Document.close()`. Note that although the call to `open()` is usually optional, the call to `close()` is never optional.

The results of calling `Document.write()` may not be immediately visible in the targeted web browser window or frame. This is because a web browser may buffer up data to output in larger chunks. Calling `Document.close()` is the only way to explicitly force all buffered output to be "flushed" and displayed in the browser window. In Navigator 2.0 and 3.0, however, output will be flushed whenever a line break occurs in the output. So for example, outputting the HTML tags `<BR>`, `<HR>`, or `<P>` would force Navigator to display all pending output. This technique does not work in Internet Explorer 3.0, however. In that browser, output is not "flushed" until the enclosing `<SCRIPT>` tag or event handler function terminates.

`Document.write()` can also be used in a third way, but only with extreme caution. When an event handler invokes `write()` on the current document (i.e., the document of which the event handler is a part), the document must first be opened, as we saw above. But opening a document discards any current contents, including any JavaScript code and function definitions. This means that the event handler calling `document.write()` on its own document cannot rely on any JavaScript functions defined in that document. In general, this technique is best avoided. If you want to dynamically generated documents without having multiple frames or windows visible, it is often easiest to use an invisible frame (one with zero height, for example) to hold the JavaScript code that does the document generation.

## See Also

"Document", "Document.close()", "Document.open()", "Document.writeln()", Chapter 14, Documents and Their Contents

Document.vlinkColor |  | Document.writeln()