« XUL Reference home [ Examples | Attributes | Properties | Methods | Related ]

An input field where the user can enter text. It is similar to the HTML input element. Only one line of text is displayed by default. The multiline attribute can be specified to display a field with multiple rows.

More information is available in the XUL tutorial.

Attributes
cols, decimalplaces, disabled, emptytext, hidespinbuttons, increment, label, max, maxlength, min, multiline, newlines, onblur, onchange, onfocus, oninput, placeholder, preference, readonly, rows, searchbutton, size, spellcheck, tabindex, timeout, type, value, wrap, wraparound
Properties
accessibleType, clickSelectsAll, decimalPlaces, decimalSymbol, defaultValue, disabled, editor, emptyText, increment, inputField, label, max, maxLength, min, placeholder, readOnly, searchButton, selectionEnd, selectionStart, size, spinButtons, tabIndex, textLength, timeout, type, value, valueNumber, wrapAround
Methods
decrease, increase, reset, select, setSelectionRange
Style classes
plain

Examples

<vbox>
  <label control="your-name" value="Enter your name:"/>
  <textbox id="your-name" value="John"/>
</vbox>
Image:XUL_ref_textbox.png

Attributes

cols
Type: integer
For multiline textboxes, the number of columns to display.
decimalplaces
Type: integer
The number of decimal places to display. The default is 0, which doesn't show any decimal places. The value Infinity may be used if you want no limit on the number of decimal places. Note that decimal numbers are stored as floats.
disabled
Type: boolean
Indicates whether the element is disabled or not. If this attribute is set, the element is disabled. Disabled elements are usually drawn with grayed-out text. If the element is disabled, it does not respond to user actions, it cannot be focused, and the command event will not fire. In the case of form elements, it will not be submitted. Do not set the attribute to true, as this will suggest you can set it to false to enable the element again, which is not the case.
The disabled attribute is allowed only for form controls. Using it with an anchor tag (an <a> link) will have no effect.
The element will, however, still respond to mouse events. To enable the element, leave this attribute out entirely.
Visible controls have a disabled property which, except for menus and menuitems, is normally preferred to use of the attribute, as it may need to update additional state.
focused
Type: boolean
This attribute is true if the element is focused.
emptytext Deprecated since Gecko 2
Type: string
A string that appears in the textbox when it has no value. This is superseded by the placeholder attribute in Gecko 2.0. The old name is retained for compatibility, but you should update your code.
hidespinbuttons
Type: boolean
If true, the number box does not have arrow buttons next to it to allow the user to adjust the value. The value may still be adjusted with the keyboard. The default value is false.
increment
Type: integer
The amount by which the curpos (for scroll bars) or value (for number boxes and scale) attribute changes when the arrows are clicked(or scales are dragged). The default value is 1.
label
Type: string
If present and not empty, this will be exposed to screen readers through the label property.
Type: integer
The maximum value that the scale or number box may be set to. The default value is 100 for scales and Infinity for number boxes.

 

maxlength
Type: integer
The maximum number of characters that the textbox allows to be entered.
min
Type: integer
The minimum value the textbox's value may take. The default value is 0.
multiline
Type: boolean
If true, the textbox displays multiple lines. If the user presses Enter, a new line is started. If false, the textbox only allows entry of one line.
newlines
Type: one of the values below
How the text box handles pastes with newlines in them.
Possible values:
pasteintact
Paste newlines unchanged
pastetofirst
Paste text up to the first newline, dropping the rest of the text
replacewithcommas
Pastes the text with the newlines replaced with commas
replacewithspaces
Pastes the text with newlines replaced with spaces
strip
Pastes the text with the newlines removed
stripsurroundingwhitespace
Pastes the text with newlines and adjacent whitespace removed
onblur
Type: script code
This event is sent when a textbox loses keyboard focus.
Note: The behavior of this event has evolved over time. Prior to Gecko 1.9 (Firefox 3), the script code would execute in the context of the anonymous HTML <input> element inside the textbox binding. From Gecko 1.9 to Gecko 12.0 (Firefox 12.0 / Thunderbird 12.0 / SeaMonkey 2.9), the script code would actually execute twice, once in the context of the anonymous HTML <input> element and once in the context of the <textbox> element itself. As of Gecko 13.0 (Firefox 13.0 / Thunderbird 13.0 / SeaMonkey 2.10), the script code only runs in the context of the <textbox> element, matching the behavior of all other event handlers.
onchange
Type: script code
This event is sent when the value of the textbox is changed. The event is not sent until the focus is moved to another element.
onfocus
Type: script code
This event is sent when a textbox receives keyboard focus.
Note: The behavior of this event has evolved over time. Prior to Gecko 1.9 (Firefox 3), the script code would execute in the context of the anonymous HTML <input> element inside the textbox binding. From Gecko 1.9 to Gecko 12.0 (Firefox 12.0 / Thunderbird 12.0 / SeaMonkey 2.9), the script code would actually execute twice, once in the context of the anonymous HTML <input> element and once in the context of the <textbox> element itself. As of Gecko 13.0 (Firefox 13.0 / Thunderbird 13.0 / SeaMonkey 2.10), the script code only runs in the context of the <textbox> element, matching the behavior of all other event handlers.
oninput
Type: script code
This event is sent when a user enters text in a textbox. This event is only called when the text displayed would change, thus it is not called when the user presses non-displayable keys.
placeholder
Type: string
A string that appears in the textbox when it has no value.
preference
Type: id
Connects the element to a corresponding preference. This attribute only has any effect when used inside a prefwindow. More information is available in the Preferences System article.
readonly
Type: boolean
If set to true, then the user cannot change the value of the element. However, the value may still be modified by a script.
rows
Type: integer
The number of rows to display in the element. If the element contains more than this number of rows, a scrollbar will appear which the user can use to scroll to the other rows. To get the actual number of rows in the element, use the getRowCount method.
searchbutton
Type: boolean
If true, the search field will only fire a command event when the user presses the search button or presses the Enter key. Otherwise, the command event is fired whenever the user modifies the value. This attribute only applies to textboxes with the type search.
size
Type: integer
The number of characters that can be displayed in the textbox.
spellcheck
Type: boolean
If true, spell checking is enabled by default for the text box; if false, spell checking is disabled by default.
If not specified, this defaults to false

The HTML

The spellcheck attribute uses values of true or false (you cannot simply add the spellcheck attribute to a given element):

<!-- spellcheck everything! -->
<input type="text" spellcheck="true" /><br />
<textarea spellcheck="true"></textarea>
<div contenteditable="true" spellcheck="true">I am some content</div>

<!-- spellcheck nothing! -->
<input type="text" spellcheck="false" /><br />
<textarea spellcheck="false"></textarea>
<div contenteditable="true" spellcheck="false">I am some content</div>

You can use spellcheck on INPUTTEXTAREA, and contenteditable elements.  Thespellcheck attribute works well paired with the autocomplete, autocapitalize, and autocorrect attributes too!

Added from David Walsh's article on Spell Check.

tabindex
Type: integer
The tab order of the element. The tab order is the order in which the focus is moved when the user presses the "tab" key. Elements with a higher tabindex are later in the tab sequence.
timeout
Type: integer
For autocomplete textboxes, the number of milliseconds before the textbox starts searching for completions. The default is 50 milliseconds. For search textboxes, the number of milliseconds before the timer fires a command event. The default is 500 milliseconds. For timed textboxes, the number of milliseconds before the timer fires a command event. There is no default. The timer starts after the user types a character. If the user types another character, the timer resets.
type
Type: one of the values below
You can set the type attribute to one of the values below for a more specialized type of textbox. Don't set the type if you wish to use a regular textbox.
autocomplete
A textbox that supports autocomplete. For more information about autocomplete textboxes, see the autocomplete documentation (XPFE [Thunderbird/SeaMonkey]) (Firefox)
number
 A textbox that only allows the user to enter numbers. In addition, arrow buttons appear next to the textbox to let the user step through values. There are several attributes that allow the number textbox to be configured, including decimalplaces, min, max, increment, wraparound, hidespinbuttons, and textbox.value.
password
A textbox that hides what is typed, used for entering passwords.
search
 A textbox intended for searching. The command event will fire as the user modifies the value. A listener for the command event should update search results. If the searchbutton attribute is set to true, the command event is only fired if the user presses the search button or presses the Enter key. You may specify grey text to appear when the search box is empty using the emptytext attribute, and a timeout may be set for the command event using the timeout attribute (defaults to 500).
timed
This textbox will fire a command event after the user types characters and a certain time has passed. The delay is set with the timeout attribute. The command event will fire if the user presses the Enter key. The timed type is deprecated in Gecko 1.9.1 and the search textbox may be used instead.
value
Type: string
The default value entered in a textbox. The attribute only holds the default value and is never modified when the user enters text. To get the updated value, use the value property. For number boxes, the default is 0 or the minimum value returned by the min property, whichever is higher.
wrap
Type: string
Set this attribute to the value off to disable word wrapping in the textbox. If this attribute is not specified, word wrapping is enabled.
wraparound
Type: boolean
If true, the value of the number box will wrap around when the maximum or minimum value is exceeded. The minimum and maximum values must both not be infinity.

Properties

accessibleType
Type: integer
A value indicating the type of accessibility object for the element.
clickSelectsAll
Type: boolean
If set to true, the contents of the textbox are selected when focused; otherwise, the cursor is left unchanged.
decimalPlaces
Type: integer
Gets and sets the value of the decimalplaces attribute.
decimalSymbol
Type: string
The character used for the decimal place indicator. The default value is a period (.)
defaultValue
Type: string
Gets and sets the the default value in a textbox.
disabled
Type: boolean
Gets and sets the value of the disabled attribute.
editor
Type: nsIEditor
A reference to the nsIEditor for editable text. This property is read only.
emptyText Deprecated since Gecko 2
Type: string
Gets and sets a string that appears in the textbox when it has no value. This is superseded by the  placeholder property in Gecko 2.0. The old name is retained for compatibility, but you should update your code.
increment
Type: integer
Gets and sets the value of the increment attribute.
inputField
Type: textbox element
In Mozilla, the XUL textbox is implemented as a wrapper around an HTML input element. This read only property holds a reference to this inner input element.
label
Type: string
Sets the label attribute. Gets the label attribute if it is present and not empty. Otherwise it returns the value of the associated label element, if applicable. Otherwise it returns the placeholder or emptyText property. The getter is mostly useful for screen readers.

Note: Prior to Firefox 3, and always in Thunderbird and SeaMonkey, the label property of an autocomplete textbox returns its value, for compatibility with the menulist element.

max
Type: integer
Gets and sets the value of the max attribute.
maxLength
Type: integer
The maximum number of characters that the textbox allows to be entered.
min
Type: integer
Gets and sets the value of the min attribute.
placeholder
Type: string
Gets and sets a string that appears in the textbox when it has no value.
readOnly
Type: boolean
If set to true, then the user cannot modify the value of the element.
searchButton
Type: boolean
Gets and sets the value of the searchbutton attribute.
selectionEnd
Type: integer
Get or set the end of the selected portion of the field's text. Use in conjuction with the selectionStart property. The value specifies the index of the character after the selection. If this value is equal to the value of the selectionStart property, no text is selected, but the value indicates the position of the caret (cursor) within the textbox.
selectionStart
Type: integer
Get or set the beginning of the selected portion of the field's text. Use in conjuction with the selectionEnd property. The value specifies the index of the first selected character.
size
Type: integer
Gets and sets the value of the size attribute.
spinButtons
Type: element
The read-only property returns a reference to the spinbuttons element used by the number box.
tabIndex
Type: integer
Gets and sets the value of the tabindex attribute.
textLength
Type: integer
Holds the length of the text entered in the textbox. This property is read-only.
timeout
Type: integer
Gets and sets the value of the timeout attribute.
type
Type: string
Gets and sets the value of the type attribute.
value
Type: string
Holds the current value of the textbox as a string. The current value may be modified by setting this property.
valueNumber
Type: number
In contrast to the value property which holds a string representation, the valueNumber property is a number containing the current value of the number box.
wrapAround
Type: boolean
Gets and sets the value of the wraparound attribute.

Methods

decrease()
Return type: no return value
Decreases the value of the scale or number box by the increment.
increase()
Return type: no return value
Increases the value of the scale or number box by the increment.
reset()
Return type: no return value
Resets the preference to its default value.
For a textbox it also clears the undo transaction list (Gecko 1.9).
select()
Return type: no return value
Selects all the text in the textbox.
setSelectionRange( start, end )
Return type: no return value
Sets the selected portion of the textbox, where the start argument is the index of the first character to select and the end argument is the index of the character after the selection. Set both arguments to the same value to move the cursor to the corresponding position without selecting text.

Inherited Methods
addEventListener(), appendChild(), blur, click, cloneNode(), compareDocumentPosition, dispatchEvent(), doCommand, focus, getAttribute(), getAttributeNode(), getAttributeNodeNS(), getAttributeNS(), getBoundingClientRect(), getClientRects(), getElementsByAttribute, getElementsByAttributeNS, getElementsByClassName(), getElementsByTagName(), getElementsByTagNameNS(), getFeature, getUserData, hasAttribute(), hasAttributeNS(), hasAttributes(), hasChildNodes(), insertBefore(), isDefaultNamespace(), isEqualNode, isSameNode, isSupported(), lookupNamespaceURI, lookupPrefix, normalize(), querySelector(), querySelectorAll(), removeAttribute(), removeAttributeNode(), removeAttributeNS(), removeChild(), removeEventListener(), replaceChild(), setAttribute(), setAttributeNode(), setAttributeNodeNS(), setAttributeNS(), setUserData

Style classes

The following classes may be used to style the element. These classes should be used instead of changing the style of the element directly since they will fit more naturally with the user's selected theme.

plain
This class causes the element to be displayed with no border or margin.

Notes

The maxlength attribute does not work when in multiline mode. A workaround using JavaScript and the onkeypress event handler as shown in abstract below may be your solution.

The XUL script:

<textbox id="pnNote" multiline="true" rows="2" cols="70" onkeypress="return pnCountNoteChars(event);"/>

The Javascript:

function pnCountNoteChars(evt) {
  //allow non character keys (delete, backspace and and etc.)
  if ((evt.charCode == 0) && (evt.keyCode != 13))
    return true;

  if (evt.target.value.length < 10) {
    return true;
  } else {
    return false;
  }
}
Interfaces
nsIAccessibleProvider, nsIDOMXULTextBoxElement