Textinput

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.

<label for="basic">Text Input:</label>
<input type="text" name="name" id="basic" value="">

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.

<label for="basic">Text Input:</label>
<input type="text" name="name" id="basic" value="" data-mini="true">

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.

<label for="clear-demo">Text Input:</label>
<input type="text" name="clear" id="clear-demo" value="" data-clear-btn="true">

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.

<div class="ui-field-contain">
  <label for="name">Text Input:</label>
  <input type="text" name="name" id="name" value="">
</div>

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:

<input id="the-search-input" type="text" data-type="search">

The script:

$( function() {
  $( "#the-search-input" ).textinput();
});

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.

<label for="textarea-a">Textarea:</label>
<textarea name="textarea" id="textarea-a">
I'm a basic textarea. If this is pre-populated with content, the height will be automatically adjusted to fit without needing to scroll. That is a pretty handy usability feature.
</textarea>

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:

<div class="ui-field-contain">
<label for="textarea">Textarea:</label>
  <textarea name="textarea" id="textarea"></textarea>
</div>

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:

$( "input" ).textinput();

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.

<label for="search-basic">Search Input:</label>
<input type="search" name="search" id="search-basic" value="">

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.

<label for="search-mini">Search Input:</label>
<input type="search" name="search-mini" id="search-mini" value="" data-mini="true">

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.

<div class="ui-field-contain">
  <label for="search-2">Search Input:</label>
  <input type="search" name="search-2" id="search-2" value="">
</div>

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:

$( ".mySearchInput" ).textinput();

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.

<label for="pre-rendered-text-field">Pre-rendered input:</label>
<div class="ui-input-text ui-body-inherit ui-shadow-inset">
  <input type="text" data-enhanced="true" data-corners="false" name="pre-rendered-text-field" id="pre-rendered-text-field">
</div>

Code examples:

Initialize the textinput with the autogrow option specified:

$( ".selector" ).textinput({
  autogrow: false
});

Get or set the autogrow option, after initialization:

// Getter
var autogrow = $( ".selector" ).textinput( "option", "autogrow" );
 
// Setter
$( ".selector" ).textinput( "option", "autogrow", false );

Code examples:

Initialize the textinput with the clearBtn option specified:

$( ".selector" ).textinput({
  clearBtn: true
});

Get or set the clearBtn option, after initialization:

// Getter
var clearBtn = $( ".selector" ).textinput( "option", "clearBtn" );
 
// Setter
$( ".selector" ).textinput( "option", "clearBtn", true );

Code examples:

Initialize the textinput with the clearBtnText option specified:

$( ".selector" ).textinput({
  clearBtnText: "Clear value"
});

Get or set the clearBtnText option, after initialization:

// Getter
var clearBtnText = $( ".selector" ).textinput( "option", "clearBtnText" );
 
// Setter
$( ".selector" ).textinput( "option", "clearBtnText", "Clear value" );

Code examples:

Initialize the textinput with the corners option specified:

$( ".selector" ).textinput({
  corners: false
});

Get or set the corners option, after initialization:

// Getter
var corners = $( ".selector" ).textinput( "option", "corners" );
 
// Setter
$( ".selector" ).textinput( "option", "corners", false );

Code examples:

Initialize the textinput with the defaults option specified:

$( ".selector" ).textinput({
  defaults: true
});

Get or set the defaults option, after initialization:

// Getter
var defaults = $( ".selector" ).textinput( "option", "defaults" );
 
// Setter
$( ".selector" ).textinput( "option", "defaults", true );

Code examples:

Initialize the textinput with the disabled option specified:

$( ".selector" ).textinput({
  disabled: true
});

Get or set the disabled option, after initialization:

// Getter
var disabled = $( ".selector" ).textinput( "option", "disabled" );
 
// Setter
$( ".selector" ).textinput( "option", "disabled", true );

Code examples:

Initialize the textinput with the enhanced option specified:

$( ".selector" ).textinput({
  enhanced: true
});

Get or set the enhanced option, after initialization:

// Getter
var enhanced = $( ".selector" ).textinput( "option", "enhanced" );
 
// Setter
$( ".selector" ).textinput( "option", "enhanced", true );

""input[type='text'], input[type='search'], :jqmData(type='search'), input[type='number'], :jqmData(type='number'), input[type='password'], input[type='email'], input[type='url'], input[type='tel'], textarea, input[type='time'], input[type='date'], input[type='month'], input[type='week'], input[type='datetime'], input[type='datetime-local'], input[type='color'], input:not([type]), input[type='file']""

$( document ).on( "mobileinit", function() {
  $.mobile.textinput.prototype.initSelector = "div.custom";
});

Code examples:

Initialize the textinput with the keyupTimeoutBuffer option specified:

$( ".selector" ).textinput({
  keyupTimeoutBuffer: 150
});

Get or set the keyupTimeoutBuffer option, after initialization:

// Getter
var keyupTimeoutBuffer = $( ".selector" ).textinput( "option", "keyupTimeoutBuffer" );
 
// Setter
$( ".selector" ).textinput( "option", "keyupTimeoutBuffer", 150 );

Code examples:

Initialize the textinput with the preventFocusZoom option specified:

$( ".selector" ).textinput({
  preventFocusZoom: true
});

Get or set the preventFocusZoom option, after initialization:

// Getter
var preventFocusZoom = $( ".selector" ).textinput( "option", "preventFocusZoom" );
 
// Setter
$( ".selector" ).textinput( "option", "preventFocusZoom", true );

Code examples:

Initialize the textinput with the theme option specified:

$( ".selector" ).textinput({
  theme: "b"
});

Get or set the theme option, after initialization:

// Getter
var theme = $( ".selector" ).textinput( "option", "theme" );
 
// Setter
$( ".selector" ).textinput( "option", "theme", "b" );

Code examples:

Initialize the textinput with the wrapperClass option specified:

$( ".selector" ).textinput({
  wrapperClass: "custom-class"
});

Get or set the wrapperClass option, after initialization:

// Getter
var wrapperClass = $( ".selector" ).textinput( "option", "wrapperClass" );
 
// Setter
$( ".selector" ).textinput( "option", "wrapperClass", "custom-class" );

• This method does not accept any arguments.

$( ".selector" ).textinput( "destroy" );

• This method does not accept any arguments.

$( ".selector" ).textinput( "disable" );

• This method does not accept any arguments.

$( ".selector" ).textinput( "enable" );

• optionName
  Type: String
  The name of the option to get.

var isDisabled = $( ".selector" ).textinput( "option", "disabled" );

• This signature does not accept any arguments.

var options = $( ".selector" ).textinput( "option" );

• optionName
  Type: String
  The name of the option to set.
• value
  Type: Object
  A value to set for the option.

$( ".selector" ).textinput( "option", "disabled", true );

• options
  Type: Object
  A map of option-value pairs to set.

$( ".selector" ).textinput( "option", { disabled: true } );

• This method does not accept any arguments.

$( ".selector" ).textinput( "refresh" );

• event
  Type: Event
• ui
  Type: Object

Note: The ui object is empty but included for consistency with other events.

$( ".selector" ).textinput({
  create: function( event, ui ) {}
});

$( ".selector" ).on( "textinputcreate", function( event, ui ) {} );

A basic example of a search input field

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>textinput demo</title>
  <link rel="stylesheet" href="//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.css">
  <script src="//code.jquery.com/jquery-1.10.2.min.js"></script>
  <script src="//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.js"></script>
</head>
<body>
 
<div data-role="page" id="page1">
  <div data-role="header">
    <h1>jQuery Mobile Example</h1>
  </div>
  <div role="main" class="ui-content">
    <label for="basic">Text Input:</label>
    <input type="text" name="name" id="basic" value="">
  </div>
</div>
 
</body>
</html>

A basic example of a search input field

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>textinput demo</title>
  <link rel="stylesheet" href="//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.css">
  <script src="//code.jquery.com/jquery-1.10.2.min.js"></script>
  <script src="//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.js"></script>
</head>
<body>
 
<div data-role="page" id="page1">
  <div data-role="header">
    <h1>jQuery Mobile Example</h1>
  </div>
  <div role="main" class="ui-content">
    <label for="search-basic">Search Input:</label>
    <input type="search" name="search" id="search-basic" value="">
  </div>
</div>
 
</body>
</html>