jQuery Keypad

A jQuery plugin that attaches a popup keyboard to a text field for mouse-driven entry or adds an inline keypad in a division or span. If you find this plugin useful please vote for it on the jQuery site.

The current version is 1.2.1 and is available under the GPL and MIT licences. For more detail see the documentation reference page. Or see a minimal page that you could use as a basis for your own investigations.

Default Settings

The keypad functionality can easily be added to a text field with appropriate default settings. Use it with a password field for more secure text entry.
You can also remove the keypad widget if it is no longer required.

Default keypad:    

  

$('#defaultKeypad').keypad();
		
$('#viewKeypad').click(function() {
	alert('The current value is: ' + $('#defaultKeypad').val());
});

$('#removeKeypad').toggle(function() {
		$(this).text('Re-attach');
		$('#defaultKeypad').keypad('destroy');
	},
	function() {
		$(this).text('Remove');
		$('#defaultKeypad').keypad();
	}
);

The defaults are:

You can override the defaults globally as shown below:

$.keypad.setDefaults({prompt: 'Please use the keypad'});

Processed fields are marked with a class of hasKeypad and are not re-processed if targetted a second time.

Invocation

You can trigger the keypad by focus on the field (the default), via an associated button, or by both. Disable or enable the fields and their triggers via a command.

Button only trigger:   

$('#buttonKeypad').keypad({showOn: 'button'});

$('.buttonDisable').toggle(function() {
		$(this).text('Enable').siblings('input').keypad('disable');
	}, function() {
		$(this).text('Disable').siblings('input').keypad('enable');
});

Image only trigger:   

$('#imageKeypad').keypad({showOn: 'button',
	buttonImageOnly: true, buttonImage: 'img/keypad.png'});

Focus and button trigger:   

$('#bothKeypad').keypad({showOn: 'both',
	buttonImage: 'img/keypad.png'});

You can also control the animation used to display the keypad and its duration. There are three standard animations (show, fadeIn, slideDown) as well as the ones from the jQuery UI effects package. Additional options for the latter may be specified with the showOptions setting.

Show : 

$('#animKeypad').keypad({showOn: 'both'});
		
$('#duration,#animation').change(function() {
	$('#animKeypad').keypad('change', {showAnim: $('#animation').val(),
		duration: $('#duration').val()});
});

Inline Keypad

You can present the keypad inline by applying it to a div or span. Make use of the value entered via the onKeypress or onClose callbacks. Or connect it with an external input field via the target setting.

Inline keypad:   

$('#inlineKeypad').keypad({onClose: useValue, prompt: '',
	closeText: 'Done', closeStatus: 'Use this value'});
		
function useValue(value) {
	alert('The entered value is ' + value);
}

$('#inlineDisable').toggle(function() {
		$(this).text('Enable');
		$('#inlineKeypad').keypad('disable');
	}, function() {
		$(this).text('Disable');
		$('#inlineKeypad').keypad('enable');
});

With a textarea: 

$('#inlineTextKeypad').keypad({onKeypress: appendValue, prompt: '',
	layout: ['àáâãäåæçèéêë', 'ìííîïñòóôõöø',
	'ðþùúûüýÿ' + $.keypad.SPACE + $.keypad.SPACE + $.keypad.SHIFT]});
		
function appendValue(key) {
	$('#inlineText').val($('#inlineText').val() + key).focus();
}

With multiple targets: 

$('#inlineTargetKeypad').keypad({target: $('.inlineTarget:first'),
	layout: $.keypad.qwertyLayout});

$('.inlineTarget').focus(function() {
	$('#inlineTargetKeypad').keypad('change', {target: this});
});

Layouts

You can alter the layout of the keypad by specifying the keys per row as a string array. Use special characters for controls:

The alphabetic character layout for the standard Qwerty keyboard is available from $.keypad.qwertyAlphabetic.

Qwerty keypad: 

var qwertyLayout = [
	$.keypad.qwertyAlphabetic[0] + $.keypad.CLOSE,
	$.keypad.HALF_SPACE + $.keypad.qwertyAlphabetic[1] +
	$.keypad.HALF_SPACE + $.keypad.CLEAR,
	$.keypad.SPACE + $.keypad.qwertyAlphabetic[2] +
	$.keypad.SHIFT + $.keypad.BACK];
$('#qwertyKeypad').keypad({keypadOnly: false, layout: qwertyLayout});

Alphabetic keypad: 

$('#alphaKeypad').keypad({keypadOnly: false,
	layout: ['abcdefghij' + $.keypad.CLOSE,
		'klmnopqrst' + $.keypad.CLEAR,
		'uvwxyz' + $.keypad.SPACE + $.keypad.SPACE +
		$.keypad.SHIFT + $.keypad.BACK]});

The full layout for the standard Qwerty keyboard is available from $.keypad.qwertyLayout.

Full keyboard entry: 

$('#fullKeypad').keypad({keypadOnly: false,
	layout: $.keypad.qwertyLayout});

Randomisation

You can provide an extra level of security by randomising the positions of the keys each time the keypad appears. The keys are shuffled by type: alphabetic, numeric, and other.

Randomised numerics: 

$('#randomKeypad').keypad({showOn: 'both', randomiseNumeric: true});

Randomised keyboard:

  

$('#randomKeyboard').keypad({showOn: 'both',
	randomiseNumeric: true, randomiseOther: true,
	layout: $.keypad.qwertyLayout});
	
$('.randomise').click(function() {
	$('#randomKeyboard').keypad('change', {
		randomiseAlphabetic: $('#alphabetic').is(':checked'),
		randomiseNumeric: $('#numeric').is(':checked'),
		randomiseOther: $('#other').is(':checked'),
		randomiseAll: $('#all').is(':checked')});
});

Unusual Characters

Use the keypad with a text field for entering unusual characters, whilst continuing to type normal characters.

Greek letters: 

$('#greekKeypad').keypad({keypadOnly: false,
	layout: ['αβγδεζ', 'ηθικλμ', 'νξοπρσ', 'τυφχψω'],
	prompt: 'Add these Greek letters'});

Mathematical symbols: 

$('#mathKeypad').keypad({keypadOnly: false,
	layout: ['÷±√≠≤≥', '²³¼½¾∞'], prompt: 'Mathematical symbols'});

Other symbols: 

$('#otherKeypad').keypad({keypadOnly: false,
	layout: ['©®™℠', '€£¥¢'], prompt: 'Other symbols'});

Text area: 

$('#areaKeypad').keypad({keypadOnly: false, prompt: '',
	layout: ['àáâãäåæçèéêë', 'ìííîïñòóôõöø',
	$.keypad.SHIFT + 'ùúûüýÿðþ' + $.keypad.CLOSE]});

Long Keys

You can have keys with more than a single character on them by providing a separator setting and delimiting the layout with it.

Dollar amount: $

$('#dollarsKeypad').keypad({separator: '|', prompt: '',
	layout: ['7|8|9|' + $.keypad.CLOSE,
		'4|5|6|' + $.keypad.CLEAR,
		'1|2|3|' + $.keypad.BACK,
		'.|0|00']});

US States: 

$('#statesKeypad').keypad({prompt: 'Select a state',
	onKeypress: chooseState, separator: '|',
	layout: ['AK|AL|AR|AZ|CA|CO|CT|DE|FL|GA',
		'HI|IA|ID|IL|IN|KS|KY|LA|MA|MD',
		'ME|MI|MN|MO|MS|MT|NC|ND|NE|NH',
		'NJ|NM|NV|NY|OH|OK|OR|PA|RI|SC',
		'SD|TN|TX|UT|VA|VT|WA|WI|WV|WY']});
		
function chooseState(key) {
	alert('You chose ' + key);
}

Continents: 

$('#continentsKeypad').keypad({prompt: 'Select a continent',
	onKeypress: chooseContinent, separator: ',',
	layout: ['Africa,Europe', 'Antarctica,North America',
		'Asia,South America', 'Australia']});
		
function chooseContinent(key) {
	alert('You chose ' + key);
}

Callback Events

Callbacks notify you when certain events occur within the keypad. Of course, you can still have an onchange handler for the input field itself.

On key press: After the current value is 

$('#pressKeypad').keypad({keypadOnly: false,
	onKeypress: function(key, value, inst) {
		$('#keypress').text(key || ' ');
		$('#current').text(value);
	}
});

On close: 

$('#closeKeypad').keypad({keypadOnly: false,
	onClose: function(value, inst) {
		alert('Closed with value ' + value);
	}
});

The beforeShow callback lets you update the keypad itself before it is shown. The keypad div and instance settings are passed as parameters.

Before show: 

$('#showKeypad').keypad({keypadOnly: false,
	beforeShow: function(div, inst) {
		$('<button id="clickMe" class="keypad-key">Click me</button>').
			appendTo(div).click(function() { alert('Clicked'); });
	}
});

Localisations

You can localise the keypad for other languages. Select a language to change the text and tooltips.

:

You need to load the appropriate language package (see list below), which adds a language set ($.keypad.regional[langCode]) and automatically sets this language as the default for all keypad fields.

<script type="text/javascript" src="jquery.keypad-fr.js"></script>

Thereafter, if desired, you can restore the original language settings.

$.keypad.setDefaults($.keypad.regional['']);

And then configure the language per keypad field.

$('#l10nKeypad').keypad($.extend({keypadClass: 'l10n'},
	$.keypad.regional['fr']));

Or you can construct the complete keyboard for your language in the local format. The following layouts are defined in the specified localisations.

: 

$('#l10nLayout').keypad($.extend({prompt: '',
	layout: $.keypad.azertyLayout}, $.keypad.regional['fr']));
	
$('#layoutSelect').change(function() {
	var details = $(this).val().split('|');
	localise(details[0], '#l10nLayout');
	$('#l10nLayout').keypad('change', {layout: $.keypad[details[1]]});
});

Keypad Styling

Control the presentation of the keypad with CSS, using the keypadClass setting to target specific keypad instances.

Flat green look: 

$('#flatKeypad').keypad({keypadClass: 'flatKeypad',
	prompt: '', closeText: 'X', clearText: '<<', backText: '<'});
#keypad-div.flatKeypad { background: #dfd; border: 1px solid #8c8;
	-moz-border-radius: 4px; -webkit-border-radius: 4px; }
.flatKeypad .keypad-key { width: 20px; border: 1px solid #8c8;
	-moz-border-radius: 4px; -webkit-border-radius: 4px;
	color: #000; background: #cfc; }
.flatKeypad .keypad-key-down { background: #8c8; }
.flatKeypad .keypad-clear { letter-spacing: -3px; }
.flatKeypad .keypad-space { width: 20px; }

Midnight buttons: 

$('#midnightKeypad').keypad({keypadClass: 'midnightKeypad',
	prompt: '', closeText: 'X', clearText: '«', backText: '‹'});
#keypad-div.midnightKeypad { background: #10085a; }
.midnightKeypad .keypad-key { width: 38px; height: 38px; padding: 5px;
	background: url(img/midnight.gif) no-repeat; border: none;
	color: #fff; font-size: 1.5em; font-weight: bold; }
.midnightKeypad .keypad-key-down { padding: 7px 3px 3px 7px;
	background: url(img/midnight.gif) no-repeat -38px 0px; }
.midnightKeypad .keypad-space { width: 38px; height: 38px; }

Dark grey keyboard: 

$('#darkKeypad').keypad({keypadClass: 'darkKeypad', keypadOnly: false,
	layout: $.keypad.qwertyLayout, prompt: ''});
#keypad-div.darkKeypad { background: #333; }
.darkKeypad .keypad-key { width: 22px; background: transparent;
	color: #fff; border: 1px outset #fff; font-weight: bold; }
.darkKeypad .keypad-key-down { border: 1px inset #fff; }
.darkKeypad .keypad-shift, .darkKeypad .keypad-back,
.darkKeypad .keypad-clear, .darkKeypad .keypad-close { width: 48px; }
.darkKeypad .keypad-spacebar { width: 152px; }
.darkKeypad .keypad-space { width: 22px; }
.darkKeypad .keypad-half-space { width: 11px; }

Alternate native style:

  

$('#styleKeypad').keypad();

$('#styleSelect').change(function() {
	$('#theme').attr('href', 'css/' + $(this).val());
});

The basic structure of the keypad is shown below:

<div class="keypadClass" id="keypad-div">
	<div class="keypad-prompt">Extra characters</div>
	<div class="keypad-row">
		<button class="keypad-key keypad-close">Close</button>
		<button class="keypad-key keypad-clear">Clear</button>
		<button class="keypad-key keypad-back">Back</button>
		...
	</div>
	<div class="keypad-row">
		<button class="keypad-key keypad-shift">Shift</button>
		<div class="keypad-space"></div>
		<button class="keypad-key">â</button>
		<button class="keypad-key keypad-key-down">é</button>
		...
	</div>
	...
	<div style="clear: both;"></div>
</div>

In the Wild

This tab highlights examples of this plugin in use "in the wild".

To add another example, please contact me (kbwood{at}iinet.com.au) and provide the plugin name, the URL of your site, its title, and a short description of its purpose and where/how the plugin is used.

Quick Reference

A full list of all possible settings is shown below. Note that not all would apply in all cases. For more detail see the documentation reference page.

$(selector).keypad({
	buttonText: '...', // Display text for trigger button
	buttonStatus: 'Open the keypad', // Status text for trigger button
	closeText: 'Close', // Display text for close link
	closeStatus: 'Close the panel', // Status text for close link
	clearText: 'Clear', // Display text for clear link
	clearStatus: 'Erase the current entry', // Status text for clear link
	backText: 'Back', // Display text for back link
	backStatus: 'Erase the previous character', // Status text for back link
	shiftText: 'Shift', // Display text for shift link
	shiftStatus: 'Toggle upper/lower case characters', // Status text for shift link
	alphabeticLayout: this.qwertyAlphabetic, // Default layout for alphabetic characters
	fullLayout: this.qwertyLayout, // Default layout for full keyboard
	isAlphabetic: this.isAlphabetic, // Function to determine if character is alphabetic
	isNumeric: this.isNumeric, // Function to determine if character is numeric
	isRTL: false, // True if right-to-left language, false if left-to-right
	
	showOn: 'focus', // 'focus' for popup on focus,
		// 'button' for trigger button, or 'both' for either
	buttonImage: '', // URL for trigger button image
	buttonImageOnly: false, // True if the image appears alone, false if it appears on a button
	showAnim: 'show', // Name of jQuery animation for popup
	showOptions: {}, // Options for enhanced animations
	duration: 'normal', // Duration of display/closure
	appendText: '', // Display text following the input box, e.g. showing the format
	keypadClass: '', // Additional CSS class for the keypad for an instance
	prompt: '', // Display text at the top of the keypad
	layout: ['123' + this.CLOSE, '456' + this.CLEAR,
		'789' + this.BACK, this.SPACE + '0'], // Layout of keys
	target: null, // Input target for an inline keypad
	keypadOnly: true, // True for entry only via the keypad, false for keyboard too
	randomiseNumeric: false, // True to randomise the numeric key positions, false to keep in order
	randomiseAlpha: false, // True to randomise the alphabetic key positions, false to keep in order
	randomiseOther: false, // True to randomise the other key positions, false to keep in order
	randomiseAll: false, // True to randomise all key positions, false to keep in order
	onKeypress: null, // Define a callback function when a key is selected
	onClose: null // Define a callback function when the panel is closed
});

$.keypad.setDefaults(settings) // Set global defaults

$.keypad.isAlphabetic(ch) // Test for an alphabetic character

$.keypad.isNumeric(ch) // Test for a numeric character

$(selector).keypad('change', settings) // Change instance settings
$(selector).keypad('change', name, value)

$(selector).keypad('destroy') // Remove keypad functionality

$(selector).keypad('show') // Show the keypad

$(selector).keypad('hide') // Hide the keypad

$(selector).keypad('enable') // Enable the keypad

$(selector).keypad('disable') // Disable the keypad

$(selector).keypad('isDisabled') // Is the keypad disabled?

Usage

  1. Include the jQuery library in the head section of your page. 
    <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script>
  2. Download and include the jQuery Keypad CSS and JavaScript in the head section of your page. 
    <style type="text/css">@import "jquery.keypad.css";</style>
<script type="text/javascript" src="jquery.keypad.js"></script>
    Alternately, you can use the packed version jquery.keypad.pack.js (11.8K vs 32.9K), or the minified version jquery.keypad.min.js (15.7K, 5.2K when zipped).
  3. Connect the keypad functionality to your input fields. 
    $(selector).keypad();
    You can include custom settings as part of this process. 
    $(selector).keypad({prompt: 'Enter here'});

For more detail see the documentation reference page. Or see a minimal page that you could use as a basis for your own investigations.

Localisations

Localisation packages are available for download and should be loaded after the main keypad code. These packages automatically apply their settings as global default values.

Other translations are welcomed.

Comments

I wish to thank you for the great job you did on Keypad plugin. It works great and is easy to tune.

Adrien Schreque

Fantastic plugin! This is working excellently.

Stuart Buckell

That's some nice work you have done with this virtual Keyboard. I've just used, and it's amazingly powerful and flexible.

Israel Rodriguez

I'm using your plugin jQuery Keypad with great success. It's very intuitive and easy to implement. I have to thank you a lot for this.

Nuno Grenhas

Contact Keith Wood at kbwood{at}iinet.com.au with comments or suggestions.

Change History

VersionDateChanges
1.2.119 Sep 2009
  • Send special values to onKeypress callback for Back and Clear buttons
  • Added target setting for updating an external field from an inline keypad
  • Added Portuguese/Brazilian localisation
1.2.025 Apr 2009
  • Added separator setting to allow keys with more than one character
  • Added beforeShow callback to allow modification of the keypad before it is displayed
  • Added $.keypad.SPACE_BAR to allow an extended length space bar
  • onKeypress now receives current key text, full value, and instance settings as parameters
  • Fixed IE6 display problems
  • Added Spanish localisation
  • Added alternate ("native") CSS
1.1.021 Mar 2009
  • Allow keypad to appear inline
  • Hide keypad on tab out
  • Call functions directly instead of as inline events
1.0.231 Jan 2009
  • Added randomiseAll setting
  • Corrected width in IE6
  • Added Google Chrome support
1.0.129 Nov 2008
  • onKeypress respects maxlength attribute on field
1.0.030 Aug 2008
  • Initial release