textarea
elementautofocus
cols
dirname
disabled
form
maxlength
name
placeholder
readonly
required
rows
wrap
interface HTMLTextAreaElement : HTMLElement { attribute boolean autofocus; attribute unsigned long cols; attribute DOMString dirName; attribute boolean disabled; readonly attribute HTMLFormElement? form; attribute long maxLength; attribute DOMString name; attribute DOMString placeholder; attribute boolean readOnly; attribute boolean required; attribute unsigned long rows; attribute DOMString wrap; readonly attribute DOMString type; attribute DOMString defaultValue; attribute DOMString value; readonly attribute unsigned long textLength; readonly attribute boolean willValidate; readonly attribute ValidityState validity; readonly attribute DOMString validationMessage; boolean checkValidity(); void setCustomValidity(DOMString error); readonly attribute NodeList labels; void select(); attribute unsigned long selectionStart; attribute unsigned long selectionEnd; attribute DOMString selectionDirection; void setSelectionRange(unsigned long start, unsigned long end, optional DOMString direction); };
The textarea
element represents a
multiline plain text edit control for the
element's raw
value. The contents of the control represent the
control's default value.
The raw value of
a textarea
control must be initially the empty
string.
A newline in a textarea
element, and in its raw value, should separate
paragraphs for the purposes of the Unicode bidirectional algorithm.
This requirement may be implemented indirectly through the style
layer. For example, an HTML+CSS user agent could implement these
requirements by implementing the CSS 'unicode-bidi' property. [BIDI] [CSS]
The readonly
attribute
is a boolean attribute used to control whether the text
can be edited by the user or not.
In this example, a text field is marked read-only because it represents a read-only file:
Filename: <code>/etc/bash.bashrc</code> <textarea name="buffer" readonly> # System-wide .bashrc file for interactive bash(1) shells. # To enable the settings / commands in this file for login shells as well, # this file has to be sourced in /etc/profile. # If not running interactively, don't do anything [ -z "$PS1" ] && return ...</textarea>
Constraint validation: If the readonly
attribute is
specified on a textarea
element, the element is
barred from constraint validation.
A textarea
element is mutable if it is neither
disabled nor has a readonly
attribute
specified.
When a textarea
is mutable, its raw value should be
editable by the user: the user agent should allow the user to edit,
insert, and remove text, and to insert and remove line breaks in the
form of "LF" (U+000A) characters. Any time the user causes
the element's raw
value to change, the user agent must queue a
task to fire a simple event that bubbles named
input
at the textarea
element. User agents may wait for a suitable break in the user's
interaction before queuing the task; for example, a user agent could
wait for the user to have not hit a key for 100ms, so as to only
fire the event when the user pauses, instead of continuously for
each keystroke.
A textarea
element has a dirty value flag, which must be
initially set to false, and must be set to true whenever the user
interacts with the control in a way that changes the raw value.
When the textarea
element's textContent
IDL attribute changes value, if the element's dirty value flag is false,
then the element's raw
value must be set to the value of the element's
textContent
IDL attribute.
The reset
algorithm for textarea
elements is to set the
element's value to
the value of the element's textContent
IDL
attribute.
If the element is mutable, the user agent should allow the user to change the writing direction of the element, setting it either to a left-to-right writing direction or a right-to-left writing direction. If the user does so, the user agent must then run the following steps:
Set the element's dir
attribute to "ltr
" if the user
selected a left-to-right writing direction, and "rtl
" if the user selected a
right-to-left writing direction.
Queue a task to fire a simple
event that bubbles named input
at the textarea
element.
The cols
attribute specifies the expected maximum number of characters per
line. If the cols
attribute
is specified, its value must be a valid non-negative
integer greater than zero. If applying the
rules for parsing non-negative integers to the
attribute's value results in a number greater than zero, then the
element's character
width is that value; otherwise, it is 20.
The user agent may use the textarea
element's character width as a hint to
the user as to how many characters the server prefers per line
(e.g. for visual user agents by making the width of the control be
that many characters). In visual renderings, the user agent should
wrap the user's input in the rendering so that each line is no wider
than this number of characters.
The rows
attribute specifies the number of lines to show. If the rows
attribute is specified, its
value must be a valid non-negative integer greater than
zero. If applying the rules for parsing
non-negative integers to the attribute's value results in a
number greater than zero, then the element's character height is that
value; otherwise, it is 2.
Visual user agents should set the height of the control to the number of lines given by character height.
The wrap
attribute is an enumerated attribute with two keywords
and states: the soft
keyword
which maps to the Soft state, and the
hard
keyword
which maps to the Hard state. The
missing value default is the Soft state.
The Soft state
indicates that the text in the textarea
is not to be
wrapped when it is submitted (though it can still be wrapped in the
rendering).
The Hard state
indicates that the text in the textarea
is to have
newlines added by the user agent so that the text is wrapped when it
is submitted.
If the element's wrap
attribute is in the Hard state, the cols
attribute must be
specified.
For historical reasons, the element's value is normalised in
three different ways for three different purposes. The raw value is the value as
it was originally set. It is not normalized. The API value is the value
used in the value
IDL
attribute. It is normalized so that line breaks use "LF" (U+000A) characters. Finally, there is the form submission value. It is normalized so that line
breaks use U+000D CARRIAGE RETURN U+000A LINE FEED (CRLF) character
pairs, and in addition, if necessary given the element's wrap
attribute, additional line
breaks are inserted to wrap the text at the given width.
The element's API value is defined to be the element's raw value with the following transformation applied:
Replace every U+000D CARRIAGE RETURN U+000A LINE FEED (CRLF) character pair from the raw value with a single "LF" (U+000A) character.
Replace every remaining U+000D CARRIAGE RETURN character from the raw value with a single "LF" (U+000A) character.
The element's value is defined to be the element's raw value with the following transformation applied:
Replace every occurrence of a "CR" (U+000D) character not followed by a "LF" (U+000A) character, and every occurrence of a "LF" (U+000A) character not preceded by a "CR" (U+000D) character, by a two-character string consisting of a U+000D CARRIAGE RETURN U+000A LINE FEED (CRLF) character pair.
If the element's wrap
attribute is in the Hard state, insert
U+000D CARRIAGE RETURN U+000A LINE FEED (CRLF) character pairs
into the string using a UA-defined algorithm so that each line has
no more than character
width characters. For the purposes of this requirement,
lines are delimited by the start of the string, the end of the
string, and U+000D CARRIAGE RETURN U+000A LINE FEED (CRLF)
character pairs.
The maxlength
attribute is a form control maxlength
attribute controlled by the
textarea
element's dirty value flag.
If the textarea
element has a maximum allowed
value length, then the element's children must be such that
the code-unit length of the value of the element's
textContent
IDL attribute is equal to or less than the
element's maximum allowed value length.
The required
attribute
is a boolean attribute. When specified, the user will
be required to enter a value before submitting the form.
Constraint validation: If the element has its
required
attribute
specified, and the element is mutable, and the element's
value is the empty string,
then the element is suffering from being missing.
The placeholder
attribute represents a short hint (a word or short phrase)
intended to aid the user with data entry when the control has no
value. A hint could be a sample value or a brief description of the
expected format. The attribute, if specified, must have a value that
contains no "LF" (U+000A) or "CR" (U+000D)
characters.
The placeholder
attribute should not be used as an alternative to a
label
. For a longer hint or other advisory text, the
title
attribute is more
appropriate.
These mechanisms are very similar but subtly
different: the hint given by the control's label
is
shown at all times; the short hint given in the placeholder
attribute is
shown before the user enters a value; and the hint in the title
attribute is shown when the user
requests further help.
User agents should present this hint to the user, after having stripped line breaks from it, when the element's value is the empty string and the control is not focused (e.g. by displaying it inside a blank unfocused control).
The dirname
attribute is a form control dirname
attribute.
The form
attribute is used to
explicitly associate the textarea
element with its
form owner. The name
attribute represents the element's name. The disabled
attribute is used to make
the control non-interactive and to prevent its value from being
submitted. The autofocus
attribute controls focus.
type
Returns the string "textarea
".
value
Returns the current value of the element.
Can be set, to change the value.
The cols
, placeholder
,
required
, rows
, and wrap
attributes must
reflect the respective content attributes of the same
name. The cols
and rows
attributes are limited
to only non-negative numbers greater than zero. The cols
attribute's default value is
20. The rows
attribute's
default value is 2. The dirName
IDL
attribute must reflect the dirname
content attribute. The
maxLength
IDL
attribute must reflect the maxlength
content attribute,
limited to only non-negative numbers. The readOnly
IDL
attribute must reflect the readonly
content
attribute.
The type
IDL
attribute must return the value "textarea
".
The defaultValue
IDL attribute must act like the element's textContent
IDL attribute.
The value
attribute must, on getting, return the element's API value; on setting, it
must set the element's raw
value to the new value, set the element's dirty value flag to true, and
should then move the text entry cursor position to the end of the
text field, unselecting any selected text and resetting the
selection direction to none.
The textLength
IDL
attribute must return the code-unit length of the
element's API
value.
The willValidate
, validity
, and validationMessage
IDL
attributes, and the checkValidity()
and setCustomValidity()
methods, are part of the constraint validation API. The
labels
IDL attribute provides a
list of the element's label
s. The select()
, selectionStart
,
selectionEnd
,
selectionDirection
,
setRangeText()
,
and setSelectionRange()
methods and IDL attributes expose the element's text selection. The
autofocus
, disabled
, form
, and name
IDL attributes are part of the
element's forms API.
Here is an example of a textarea
being used for
unrestricted free-form text input in a form:
<p>If you have any comments, please let us know: <textarea cols=80 name=comments></textarea></p>
To specify a maximum length for the comments, one can use
the maxlength
attribute:
<p>If you have any short comments, please let us know: <textarea cols=80 name=comments maxlength=200></textarea></p>
To give a default value, text can be included inside the element:
<p>If you have any comments, please let us know: <textarea cols=80 name=comments>You rock!</textarea></p>
To have the browser submit the directionality of
the element along with the value, the dirname
attribute can be
specified:
<p>If you have any comments, please let us know (you may use either English or Hebrew for your comments): <textarea cols=80 name=comments dirname=comments.dir></textarea></p>