---
title: textbox
slug: Mozilla/Tech/XUL/textbox
translation_of: Archive/Mozilla/XUL/textbox
---
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, onchange, 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>
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-
-
类型:boolean
-
表示元素是被禁用的。
如果这个元素的disabled属性被设置为true，表示元素被禁用，被禁用的属性在页面上通常会显示灰色文本，它无法响应用户的操作，它也无法得到光标。
然而，这个元素仍然能够响应鼠标事件，如果要启用这个元素，把disabled设置为false
示例：
// Disabling an element
document.getElementById('buttonRemove').setAttribute("disabled", "true");
// Enabling back an element by removing the "disabled" attribute
document.getElementById('buttonRemove').removeAttribute("disabled");
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.
-
increment
-
类型:整数
-
拖动刻度条控件(
scale元素)中的拉杆,点击滚动条控件(scrollbar元素)中的箭头(拖动拉杆也可以),点击数字输入框(type属性为number的textbox元素)中的箭头时,其curpos属性或者value属性每次改变的数字值,默认值为1.
label - Type: string
- If present and not empty, this will be exposed to screen readers through the label property.
-
类型:整数
-
设置刻度条控件(scale元素)或者数字输入框控件(type属性为number的textbox元素)中能输入的最大数字.刻度条控件中,该属性的默认值为100,数字输入框中,该属性的默认值为无穷大.
maxlength- Type: integer
- The maximum number of characters that the textbox allows to be entered.
-
min
-
类型:整数
-
该控件可以有的最小的整数值,默认值为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
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.
placeholder - Type: string
- A string that appears in the textbox when it has no value.
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.
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):
<input type="text" spellcheck="true" /><br />
<textarea spellcheck="true"></textarea>
<div contenteditable="true" spellcheck="true">I am some content</div>
<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 INPUT, TEXTAREA, 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
- 当用户按下 "tab" 键时焦点移动到元素上的顺序。
tabindex 数字越大，顺序越靠后。
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.
-
decimalSymbol
-
Type: string
-
The character used for the decimal place indicator. The default value is a period (.)
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.
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
-
类型:整数
-
获取或设置
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.
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.
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
-
类型:字符串
-
读取或设置该
textbox元素中的文本内容.
-
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.
Methods
-
decrease()
-
Return type: no return value
-
Decreases the value of the scale or number box by the
increment.
-
increase()
-
返回值类型: 无返回值
-
增大刻度条控件(scale元素)或者数字输入框控件(type属性为number的textbox元素)中的数字值(按照其
increment属性指定的值).
-
reset()
-
返回值:无返回值
-
将用户偏好重置为默认值.
-
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 from XUL element
blur, click, doCommand, focus, getElementsByAttribute Inherited from DOM element
addEventListener(), appendChild(), dispatchEvent(), getAttribute(), getAttributeNode(), getAttributeNodeNS(), getAttributeNS(), getElementsByTagName(), getElementsByTagNameNS(), hasAttribute(), hasAttributeNS(), hasAttributes(), hasChildNodes(), insertBefore(), isSupported(), normalize(), removeAttribute(), removeAttributeNode(), removeAttributeNS(), removeChild(), removeEventListener(), replaceChild(), setAttribute(), setAttributeNode(), setAttributeNodeNS(), setAttributeNS() |
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
