4.10.20 APIs for the text field selections

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 setSelectionRange(unsigned long start, unsigned long end, optional DOMString direction);

These methods and attributes expose and control the selection of input and textarea text fields.

element . select()

Selects everything in the text field.

element . selectionStart [ = value ]

Returns the offset to the start of the selection.

Can be set, to change the start of the selection.

element . selectionEnd [ = value ]

Returns the offset to the end of the selection.

Can be set, to change the end of the selection.

element . 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".

element . 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).

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 in 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.

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);

...where control is the input or textarea element.

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);

...where control is the input or textarea element.