The input
and textarea
elements define
the following members in their DOM interfaces for handling their
selection:
void select(); attribute unsigned long selectionStart; attribute unsigned long selectionEnd; attribute DOMString selectionDirection; void setRangeText(DOMString replacement); void setRangeText(DOMString replacement, unsigned long start, unsigned long end, optional SelectionMode selectionMode); void setSelectionRange(unsigned long start, unsigned long end, optional DOMString direction = "preserve");
The setRangeText
method
uses the following enumeration:
enum SelectionMode { 'select', 'start', 'end', 'preserve', };
These methods and attributes expose and control the selection of
input
and textarea
text fields.
select
()Selects everything in the text field.
selectionStart
[ = value ]Returns the offset to the start of the selection.
Can be set, to change the start of the selection.
selectionEnd
[ = value ]Returns the offset to the end of the selection.
Can be set, to change the end of the selection.
selectionDirection
[ = value ]Returns the current direction of the selection.
Can be set, to change the direction of the selection.
The possible values are "forward
", "backward
", and "none
".
setSelectionRange
(start, end [, direction] )Changes the selection to cover the given substring in the given direction. If the direction is omitted, it will be reset to be the platform default (none or forward).
setRangeText
(replacement [, start, end [, selectionMode ] ] )Replaces a range of text with the new text. If the start and end arguments are not provided, the range is assumed to be the selection.
The final argument determines how the selection should be set after the text has been replaced. The possible values are:
select
"start
"end
"preserve
"When these methods and attributes are used with
input
elements while they don't apply, they must throw
an InvalidStateError
exception. Otherwise, they must
act as described below.
For input
elements, these methods and attributes
must operate on the element's value. For textarea
elements, these methods and attributes must operate on the element's
raw value.
Where possible, user interface features for changing the text
selection in input
and textarea
elements
must be implemented in terms of the DOM API described in this
section, so that, e.g., all the same events fire.
The selections of input
and textarea
elements have a direction, which is either forward,
backward, or none. This direction is set when the user
manipulates the selection. The exact meaning of the selection
direction depends on the platform.
On Windows, the direction indicates the position of the caret relative to the selection: a forward selection has the caret at the end of the selection and a backward selection has the caret at the start of the selection. Windows has no none direction. On Mac, the direction indicates which end of the selection is affected when the user adjusts the size of the selection using the arrow keys with the Shift modifier: the forward direction means the end of the selection is modified, and the backwards direction means the start of the selection is modified. The none direction is the default on Mac, it indicates that no particular direction has yet been selected. The user sets the direction implicitly when first adjusting the selection, based on which directional arrow key was used.
The select()
method
must cause the contents of the text field to be fully selected, with
the selection direction being none, if the platform support
selections with the direction none, or otherwise
forward. The user agent must then queue a task
to fire a simple event that bubbles named select
at the element, using the
user interaction task source as the task source.
The selectionStart
attribute must, on getting, return the offset (in logical order) to
the character that immediately follows the start of the
selection. If there is no selection, then it must return the offset
(in logical order) to the character that immediately follows the
text entry cursor.
On setting, it must act as if the setSelectionRange()
method had been called, with the new value as the first argument;
the current value of the selectionEnd
attribute as the second argument, unless the current value of the
selectionEnd
is
less than the new value, in which case the second argument must also
be the new value; and the current value of the selectionDirection
as the third argument.
The selectionEnd
attribute must, on getting, return the offset (in logical order) to
the character that immediately follows the end of the selection. If
there is no selection, then it must return the offset (in logical
order) to the character that immediately follows the text entry
cursor.
On setting, it must act as if the setSelectionRange()
method had been called, with the current value of the selectionStart
attribute as the first argument, the new value as the second
argument, and the current value of the selectionDirection
as the third argument.
The selectionDirection
attribute must, on getting, return the string corresponding to the
current selection direction: if the direction is forward,
"forward
"; if the direction is
backward, "backward
"; and otherwise,
"none
".
On setting, it must act as if the setSelectionRange()
method had been called, with the current value of the selectionStart
attribute as the first argument, the current value of the selectionEnd
attribute as the second argument, and the new value as the third
argument.
The setSelectionRange(start, end, direction)
method must set the selection
of the text field to the sequence of characters starting with the
character at the startth position (in logical
order) and ending with the character at the (end-1)th position. Arguments greater than the
length of the value of the text field must be treated as pointing at
the end of the text field. If end is less than
or equal to start then the start of the
selection and the end of the selection must both be placed
immediately before the character with offset end. In UAs where there is no concept of an empty
selection, this must set the cursor to be just before the character
with offset end. The direction of the selection
must be set to backward if direction is a
case-sensitive match for the string "backward
", forward if direction is a case-sensitive match for
the string "forward
" or if the platform does
not support selections with the direction none, and
none otherwise (including if the argument is omitted). The
user agent must then queue a task to fire a
simple event that bubbles named select
at the element, using the
user interaction task source as the task source.
The setRangeText(replacement, start, end, selectMode)
method must run the following steps:
If the method has only one argument, then let start and end have the values
of the selectionStart
attribute and the selectionEnd
attribute respectively.
Otherwise, let start, end have the values of the second and third arguments respectively.
If start is greater than end, then throw an IndexSizeError
exception and abort these steps.
If either start or end are greater than the length of the value of the text field, then set them to the length of the value of the text field.
Let selection start be the current value
of the selectionStart
attribute.
Let selection end be the current value
of the selectionEnd
attribute.
If start is less than end, delete the sequence of characters starting with the character at the selection startth position (in logical order) and ending with the character at the (selection end-1)th position.
Insert the value of the first argument into the text of the value of the text field, immediately before the startth character.
Run the appropriate set of substeps from the following list:
select
"Let selection start be start.
Let selection end be end.
start
"Let selection start and selection end be start.
end
"Let selection start and selection end be end.
preserve
", or if the argument was omittedLet old length be end minus start.
Let new length be the length of the value of the first argument (the newly inserted text).
Let delta be new length minus old length.
If selection start is greater than end, then increment it by delta. (If delta is negative, i.e. the new text is shorter than the old text, then this will decrease the value of selection start.)
Otherwise: if selection start is greater than start, then set it to start. (This snaps the start of the selection to the start of the new text if it was in the middle of the text that it replaced.)
If selection end is greater than end, then increment it by delta in the same way.
Otherwise: if selection end is greater than start, then set it to end. (This snaps the end of the selection to the end of the new text if it was in the middle of the text that it replaced.)
Set the selection of the text field to the sequence of characters starting with the character at the selection startth position (in logical order) and ending with the character at the (selection end-1)th position. In UAs where there is no concept of an empty selection, this must set the cursor to be just before the character with offset end. The direction of the selection must be set to forward if the platform does not support selections with the direction none, and none otherwise.
Queue a task to fire a simple
event that bubbles named select
at the element, using the
user interaction task source as the task
source.
All elements to which this API applies have either a selection or a text entry cursor position at all times (even for elements that are not being rendered). User agents should follow platform conventions to determine their initial state.
Characters with no visible rendering, such as U+200D ZERO WIDTH JOINER, still count as characters. Thus, for instance, the selection can include just an invisible character, and the text insertion cursor can be placed to one side or another of such a character.
To obtain the currently selected text, the following JavaScript suffices:
var selectionText = control.value.substring(control.selectionStart, control.selectionEnd);
To add some text at the start of a text control, while maintaining the text selection, the three attributes must be preserved:
var oldStart = control.selectionStart; var oldEnd = control.selectionEnd; var oldDirection = control.selectionDirection; var prefix = "http://"; control.value = prefix + control.value; control.setSelectionRange(oldStart + prefix.length, oldEnd + prefix.length, oldDirection);