Textinput Widgetversion added: 1.0
Description: Creates a textinput widget for textinput, textarea or search input
Text Input
Text inputs and textareas are coded with standard HTML elements, then enhanced by jQuery Mobile to make them more attractive and useable on a mobile device.
To collect standard alphanumeric text, use an input
with a type="text"
attribute. Set the for
attribute of the label
to match the id
of the input
so they are semantically associated. It's possible to accessibly hide the label if it's not desired in the page layout, but we require that it is present in the markup for semantic and accessibility reasons.
1
2
|
|
This will produce a basic text input. The default styles set the width of the input to 100% of the parent container and stack the label on a separate line.
Mini version
For a more compact version that is useful in toolbars and tight spaces, add the data-mini="true"
attribute to the element to create a mini version.
1
2
|
|
This will produce an input that is not as tall as the standard version and has a smaller text size.
Clear button option
The clearButton
extension provides the clearBtn
option.
To add a clear button to any input (like the search input), add the data-clear-btn="true"
attribute. The text for this clear button can be customized via the data-clear-btn-text="clear input"
attribute. Search buttons have the clear button by default and cannot be controlled by this option. Note that this is available for all the input types below except for those coded via textarea
elements.
1
2
|
|
This markup creates a text input with a clear button that becomes visible as soon as a character has been entered.
Field containers
Optionally wrap the text input in a container with class ui-field-contain
to help visually group it in a longer form.
Note: The data-
attribute data-role="fieldcontain"
is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class ui-field-contain
instead.
1
2
3
4
|
|
The text input is now displayed like this:
More text input types
In jQuery Mobile, you can use existing and new HTML5 input types such as password
, email
, tel
, number
, and more. Some type values are rendered differently across browsers. For example, Chrome renders the range
input as a slider. jQuery Mobile standardizes the appearance of range
and search
by dynamically changing their type to text
. You can configure which input types are degraded to text
with the page
plugin's options.
One major advantage of using these more specific input types if that on mobile devices, specialized keyboards that speed data entry are offered in place of the standard text keyboard. Try the following inputs on a mobile device to see which display custom keyboards on various platforms.
Search input outside the page
jQuery Mobile-styled textinput
widgets can be placed outside jQuery Mobile pages. To do so, specify their input type as type="text"
, add the attribute data-type="search"
, and manually call the textinput
plugin on the element.
The markup:
1
|
|
The script:
1
2
3
|
|
Textareas
For multi-line text inputs, use a textarea
element. The autogrow
extension provides functionality for auto-growing the height of the textarea to avoid the need for an internal scrollbar.
Set the for
attribute of the label
to match the id
of the textarea
so they are semantically associated, and wrap them in a div
with class ui-field-contain
to group them.
Note: The data-
attribute data-role="fieldcontain"
is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class ui-field-contain
instead.
1
2
3
4
|
|
This will produce a basic textarea with the width set to 100% of the parent container and the label stacked on a separate line. The textarea will grow to fit new lines as you type:
1
2
3
4
|
|
The textarea is displayed like this and will grow to fit new lines as you type:
Calling the textinput plugin
This plugin will auto initialize on any page that contains a textarea or any of the text input types listed above without any need for a data-role
attribute in the markup. However, if needed, you can directly call the textinput
plugin on any selector, just like any jQuery plugin:
1
|
|
Degraded input types
The location of the map of input type degradations in the page plugin is deprecated as of 1.4.0. As of 1.5.0 the input type degradation functionality will be implemented by the degradeInputs
module.
jQuery Mobile degrades several HTML5 input types back to type=text or type=number after adding enhanced controls. For example, inputs with a type of range are enhanced with a custom slider control, and their type is set to number to offer a usable form input alongside that slider. Inputs with a type of search are degraded back to type=text after we add our own themeable search input styling.
The degradeInputs
module contains a list of input types that are set to either true which means they'll degrade to type=text, false which means they'll be left alone, or a string such as "number", which means they'll be converted to that type (such as the case of type=range).
You can configure which types are changed via $.mobile.degradeInputs
, which has properties: color, date, datetime, "datetime-local", email, month, number, range, search, tel, time, url, and week. Be sure to configure this inside an event handler bound to the mobileinit
event, so that it applies to the first page as well as subsequent pages that are loaded.
Search Input
Search inputs are a new HTML type styled with pill-shaped corners and an "x" icon to clear the field once you start typing. Start with an input with a type="search" attribute in your markup.
Set the for
attribute of the label
to match the id
of the input
so they are semantically associated. It's possible to accessibly hide the label if it's not desired in the page layout, but we require that it is present in the markup for semantic and accessibility reasons.
1
2
|
|
This will produce a basic search input. The default styles set the width of the input to 100% of the parent container and stack the label on a separate line.
Mini version
For a more compact version that is useful in toolbars and tight spaces, add the data-mini="true"
attribute to the element to create a mini version.
1
2
|
|
This will produce a search input that is not as tall as the standard version and has a smaller text size.
Field containers
Optionally wrap the search input in a container with tlass ui-field-contain
to help visually group it in a longer form.
Note: The data-
attribute data-role="fieldcontain"
is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class ui-field-contain
instead.
1
2
3
4
|
|
The search input is now displayed like this:
Theming
The data-theme
attribute can be added to the search input to set the theme to any swatch letter.
Setting the clear button text
The text for the button used to clear the search input of text can be configured for all search inputs by binding to the mobileinit
event and setting the
$.mobile.textinput.prototype.options.clearBtnText
property to a string of your choosing.
This option is provided by the clearButton
extension.
Calling the textinput plugin
This plugin will auto-initialize on any page that contains a text input with the type="search"
attribute without any need for a data-role
attribute in the markup. However, if needed, you can directly call the textinput
plugin on a selector, just like any jQuery plugin:
1
|
|
Providing pre-rendered markup
You can improve the load time of your page by providing the markup that the textinput widget would normally create during its initialization.
By providing this markup yourself, and by indicating that you have done so by setting the attribute data-enhanced="true"
, you instruct the textinput widget to skip these DOM manipulations during instantiation and to assume that the required DOM structure is already present.
When you provide such pre-rendered markup you must also set all the classes that the framework would normally set, and you must also set all data attributes whose values differ from the default to indicate that the pre-rendered markup reflects the non-default value of the corresponding widget option.
The textinput widget wraps input
-based widgets in div
used for creating the style. textarea
elements are not wrapped in such a div
.
In the example below, we add the attribute data-corners="false"
to the input, because the class ui-corner-all
is absent from the wrapper, indicating that the value of the "corners" option should be false.
1
2
3
4
|
|
Options
autogrow
true
autogrow
extension.
Whether to update the size of the textarea
element upon first appearance, as well as upon a change in the content of the element.
This option applies only to textinput widgets based on textarea
elements.
This option is also exposed as a data attribute: data-autogrow="false"
.
Initialize the textinput with the autogrow
option specified:
1
2
3
|
|
Get or set the autogrow
option, after initialization:
1
2
3
4
5
|
|
clearBtn
false
clearButton
extension.
Adds a clear button to the input when set to true
.
This option applies only to textinput widgets based on input
elements.
This option is also exposed as a data attribute: data-clear-btn="true"
.
Initialize the textinput with the clearBtn
option specified:
1
2
3
|
|
Get or set the clearBtn
option, after initialization:
1
2
3
4
5
|
|
clearBtnText
"Clear text"
clearButton
extension.
The text description for the optional clear button, useful for assistive technologies like screen readers.
This option applies only to textinput widgets based on input
elements.
This option is also exposed as a data attribute: data-clear-btn-text="Clear value"
.
Initialize the textinput with the clearBtnText
option specified:
1
2
3
|
|
Get or set the clearBtnText
option, after initialization:
1
2
3
4
5
|
|
corners
true
true
by adding the class ui-corner-all
to the textinput widget's outermost element.
This option is also exposed as a data attribute: data-corners="false"
.
Initialize the textinput with the corners
option specified:
1
2
3
|
|
Get or set the corners
option, after initialization:
1
2
3
4
5
|
|
defaults
false
true
indicates that other widgets options have default values and causes jQuery Mobile's widget autoenhancement code to omit the step where it retrieves option values from data attributes. This can improve startup time.
This option is also exposed as a data attribute: data-defaults="true"
.
Initialize the textinput with the defaults
option specified:
1
2
3
|
|
Get or set the defaults
option, after initialization:
1
2
3
4
5
|
|
disabled
false
true
.
This option is also exposed as a data attribute: data-disabled="true"
.
Initialize the textinput with the disabled
option specified:
1
2
3
|
|
Get or set the disabled
option, after initialization:
1
2
3
4
5
|
|
enhanced
false
This option is also exposed as a data attribute: data-enhanced="true"
.
Initialize the textinput with the enhanced
option specified:
1
2
3
|
|
Get or set the enhanced
option, after initialization:
1
2
3
4
5
|
|
initSelector
See below
The default initSelector
for the textinput widget is:
1
|
|
Note: This option is deprecated in 1.4.0 and will be removed in 1.5.0.
As of jQuery Mobile 1.4.0, the initSelector
is no longer a widget option. Instead, it is declared directly on the widget prototype. Thus, you may specify a custom value by handling the mobileinit
event and overwriting the initSelector
on the prototype:
1
2
3
|
|
Note: Remember to attach the mobileinit
handler after you have loaded jQuery, but before you load jQuery Mobile, because the event is triggered as part of jQuery Mobile's loading process.
The value of this option is a jQuery selector string. The framework selects elements based on the value of this option and instantiates textinput widgets on each of the resulting list of elements.
(version deprecated: 1.4.0)keyupTimeoutBuffer
100
autogrow
extension.
The amount of time (in milliseconds) to wait between the occurence of a keystroke and the resizing of the textarea
element. If another keystroke occurs within this time, the resizing is postponed by another period of time of the same length.
This option applies only to textinput widgets based on textarea
elements.
This option is also exposed as a data attribute: data-keyup-timeout-buffer="150"
.
Initialize the textinput with the keyupTimeoutBuffer
option specified:
1
2
3
|
|
Get or set the keyupTimeoutBuffer
option, after initialization:
1
2
3
4
5
|
|
mini
null (false)
true
, this will display a more compact version of the textinput that uses less vertical height by applying the ui-mini
class to the outermost element of the textinput widget.
This option is also exposed as a data attribute: data-mini="true"
.
preventFocusZoom
true on iOS platforms
This option is also exposed as a data attribute: data-prevent-focus-zoom="true"
.
Initialize the textinput with the preventFocusZoom
option specified:
1
2
3
|
|
Get or set the preventFocusZoom
option, after initialization:
1
2
3
4
5
|
|
theme
null, inherited from parent
Possible values: swatch letter (a-z).
This option is also exposed as a data attribute: data-theme="b"
.
Initialize the textinput with the theme
option specified:
1
2
3
|
|
Get or set the theme
option, after initialization:
1
2
3
4
5
|
|
wrapperClass
""
This option is also exposed as a data attribute: data-wrapper-class="true"
.
Initialize the textinput with the wrapperClass
option specified:
1
2
3
|
|
Get or set the wrapperClass
option, after initialization:
1
2
3
4
5
|
|
Methods
destroy()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the destroy method:
1
|
|
disable()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the disable method:
1
|
|
enable()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the enable method:
1
|
|
option( optionName )Returns: Object
optionName
.-
optionNameType: StringThe name of the option to get.
Invoke the method:
1
|
|
option()Returns: PlainObject
- This signature does not accept any arguments.
Invoke the method:
1
|
|
option( optionName, value )Returns: jQuery (plugin only)
optionName
.-
optionNameType: StringThe name of the option to set.
-
valueType: ObjectA value to set for the option.
Invoke the method:
1
|
|
option( options )Returns: jQuery (plugin only)
-
optionsType: ObjectA map of option-value pairs to set.
Invoke the method:
1
|
|
refresh()Returns: jQuery (plugin only)
This method is provided by the autogrow extension, and it sets the height of the textarea
element based on its contents. You should call this method when the textarea
element becomes visible to make sure that its initial height matches its contents.
- This method does not accept any arguments.
Invoke the refresh method:
1
|
|
Events
create( event, ui )Type: textinputcreate
Note: The ui
object is empty but included for consistency with other events.
Initialize the textinput with the create callback specified:
1
2
3
|
|
Bind an event listener to the textinputcreate event:
1
|
|
Examples:
A basic example of a search input field
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
|
|
Demo:
A basic example of a search input field
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
|
|