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').click(function() {
	var destroy = $(this).text() === 'Remove';
	$(this).text(destroy ? 'Re-attach' : 'Remove');
	$('#defaultKeypad').keypad(destroy ? 'destroy' : {});
});

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 is-keypad and are not re-processed if targeted 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').click(function() {
	var enable = $(this).text() === 'Enable';
	$(this).text(enable ? 'Disable' : 'Enable').siblings('input').keypad(enable ? 'enable' : 'disable');
});

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'});

var anims = ['show', 'fadeIn', 'slideDown', 'blind', 'blind', 'bounce', 'clip',
	'clip', 'drop', 'drop', 'fold', 'fold', 'slide', 'slide', ''];
var animOpts = [null, null, null, {}, {direction: 'horizontal'}, {}, {},
	{direction: 'horizontal'}, {}, {direction: 'up'}, {},
	{horizFirst: true}, {}, {direction: 'up'}, {}];

$('#duration,#animation').change(function() {
	var index = parseInt($('#animation').val(), 10);
	$('#animKeypad').keypad('option', {showAnim: anims[index],
		showOptions: animOpts[index], 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').click(function() {
	var enable = $(this).text() === 'Enable';
	$(this).text(enable ? 'Disable' : 'Enable');
	$('#inlineKeypad').keypad(enable ? 'enable' : 'disable');
});

With a textarea:

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

With multiple targets:

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

var keypadTarget = null;
$('.inlineTarget').focus(function() {
	if (keypadTarget != this) {
		keypadTarget = this;
		$('#inlineTargetKeypad').keypad('option', {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('option', {
		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: ['αβγδεζ', 'ηθικλμ', 'νξοπρσ', 'τυφχψω', $.keypad.SHIFT],
	prompt: 'Add these Greek letters'});

Mathematical symbols:

$('#mathKeypad').keypad({keypadOnly: false,
	layout: ['÷±≠≤≥', '½⅓⅔¼¾', $.keypad.SHIFT],
	toUpper: function(ch) {
		return {'÷': 'º', '±': '¹', '≠': '²', '≤': '³', '≥': 'ⁿ',
			'⅓': '⅛', '⅔': '⅜', '¼': '⅝', '¾': '⅞'}[ch] || ch;
	},
	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);
}
Control Keys

You can define additional control keys to execute your own actions via the addKeyDef function. Specify a variable name for including the key in a layout, a name for styling and finding the display text, and the function that implements the action.

Start/end keys:

.keypad-start, .keypad-end { background: #ff0; }
function moveCursor(input, pos) {
	if (input[0].setSelectionRange) { // Mozilla
		input[0].setSelectionRange(pos, pos);
	}
	else if (input[0].createTextRange) { // IE
		var range = input[0].createTextRange();
		range.move('character', pos);
		range.select();
	}
	input.focus();
}

$.keypad.addKeyDef('START', 'start',
	function(inst) { moveCursor(this, 0); });
$.keypad.addKeyDef('END', 'end',
	function(inst) { moveCursor(this, this.val().length); });

$('#startEndKeypad').keypad({prompt: '', keypadOnly: false,
	startText: '|<', startStatus: 'Move to start',
	endText: '>|', endStatus: 'Move to end',
	layout: ['789' + $.keypad.CLOSE,
		'456' + $.keypad.CLEAR,
		'123' + $.keypad.BACK,
		'.0' + $.keypad.SPACE + $.keypad.START + $.keypad.END]});
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.regionalOptions[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.regionalOptions['']);

And then configure the language per keypad field.

$('#l10nKeypad').keypad($.extend({keypadClass: 'l10n'},
	$.keypad.regionalOptions['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.regionalOptions['fr']));
	
$('#layoutSelect').change(function() {
	var details = $(this).val().split('|');
	localise(details[0], '#l10nLayout');
	$('#l10nLayout').keypad('option', {layout: $.keypad[details[1]]});
});
Keypad Styling

You can control the appearance of the keypad via CSS and the keypadClass option. The latter is set as a class value for the keypad instance, allowing it to be individually customised.

Flat green look:

$('#flatKeypad').keypad({keypadClass: 'flatKeypad',
	prompt: '', closeText: 'X', clearText: '<<', backText: '<'});
.keypad-popup.flatKeypad { background: #dfd; border: 1px solid #8c8;
	-moz-border-radius: 0.25em; -webkit-border-radius: 0.25em; }
.flatKeypad .keypad-key, .flatKeypad .keypad-special {
	width: 1.5em; border: 1px solid #8c8; -moz-border-radius: 0.25em;
	-webkit-border-radius: 0.25em; color: #000; background: #cfc; }
.flatKeypad .keypad-key-down { background: #8c8; }
.flatKeypad .keypad-clear { letter-spacing: -3px; text-align: left; }
.flatKeypad .keypad-space { width: 1.5em; }

Midnight buttons:

$('#midnightKeypad').keypad({keypadClass: 'midnightKeypad',
	prompt: '', closeText: 'X', clearText: '«', backText: '‹'});
.keypad-popup.midnightKeypad { background: #10085a; }
.midnightKeypad .keypad-key, .midnightKeypad .keypad-special {
	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: 8px; }

Dark grey keyboard:

$('#darkKeypad').keypad({keypadClass: 'darkKeypad', keypadOnly: false,
	layout: $.keypad.qwertyLayout, prompt: ''});
.keypad-popup.darkKeypad { background: #333; }
.darkKeypad .keypad-key, .darkKeypad .keypad-special { width: 1.5em; background: transparent;
	color: #fff; border: 0.125em outset #fff; font-weight: bold; }
.darkKeypad .keypad-key-down { border: 0.125em inset #fff; }
.darkKeypad .keypad-shift, .darkKeypad .keypad-back,
.darkKeypad .keypad-clear, .darkKeypad .keypad-close,
.darkKeypad .keypad-enter { width: 3.25em; }
.darkKeypad .keypad-spacebar { width: 10.25em; }
.darkKeypad .keypad-space { width: 1.5em; }
.darkKeypad .keypad-half-space { width: 0.75em; }

Alternate native style:

 

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

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

To use ThemeRoller styling instead set the useThemeRoller option and include your favourite theme CSS.

ThemeRoller styling:

 

$('#themeRollerKeypad').keypad({useThemeRoller: true,
	keypadOnly: false, layout: $.keypad.qwertyLayout, prompt: 'Using ThemeRoller'});
	
$('#themeRollerSelect').change(function() {
	$('#themeUI').attr('href', 'themesDemo/' + $(this).val() + '/jquery-ui.css');
});

The snippet below shows the structure of the keypad along with the CSS classes you can target for customisation. The ui-* classes are only present if useThemeRoller is true.

<div class="keypadClass keypad-popup or keypad-inline ui-widget ui-widget-content">
	<div class="keypad-prompt ui-widget-header ui-corner-all">Extra characters</div>
	<div class="keypad-row">
		<button class="keypad-special keypad-close ui-state-default ui-state-highlight">Close</button>
		<button class="keypad-special keypad-clear ui-state-default ui-state-highlight">Clear</button>
		<button class="keypad-special keypad-back ui-state-default ui-state-highlight">Back</button>
		...
	</div>
	<div class="keypad-row">
		<button class="keypad-special keypad-shift ui-state-default ui-state-highlight">Shift</button>
		<div class="keypad-space"></div>
		<button class="keypad-key ui-state-default">â</button>
		<button class="keypad-key keypad-key-down ui-state-default ui-state-active">é</button>
		...
	</div>
	...
	<div style="clear: both;"></div>
</div>

To change the overall size of the keypad just override the basic font size.

.keypad-popup, .keypad-inline, .keypad-key, .keypad-special { font-size: 20px; }
In the Wild

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

To add another example, please contact me (wood.keith{at}optusnet.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
	spacebarText: '&#160;', // Display text for space bar
	spacebarStatus: 'Space', // Status text for space bar
	enterText: 'Enter', // Display text for carriage return
	enterStatus: 'Carriage return', // Status text for carriage return
	tabText: '→', // Display text for tab
	tabStatus: 'Horizontal tab', // Status text for tab
	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
	toUpper: this.toUpper, // Function to convert characters to upper case
	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
	useThemeRoller: false, // True to add ThemeRoller classes
	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
	separator: '', // Separator character between keys
	target: null, // Input target for an inline keypad
	keypadOnly: true, // True for entry only via the keypad, false for keyboard too
	randomiseAlphabetic: false, // True to randomise the alphabetic key positions, false to keep in order
	randomiseNumeric: false, // True to randomise the numeric 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
	beforeShow: null, // Callback before showing the keypad
	onKeypress: null, // Define a callback function when a key is selected
	onClose: null // Define a callback function when the panel is closed
});

$.keypad.regionalOptions[] // Language/country-specific localisations

$.keypad.CLOSE // Key marker for close button
$.keypad.CLEAR // Key marker for clear button
$.keypad.BACK // Key marker for back button
$.keypad.SHIFT // Key marker for shift button
$.keypad.SPACE_BAR // Key marker for space bar button
$.keypad.ENTER // Key marker for enter button
$.keypad.SPACE // Key marker for an empty space
$.keypad.HALF_SPACE // Key marker for an empty half space

$.keypad.numericLayout // Standard numeric layout
$.keypad.qwertyAlphabetic // Standard US keyboard alphabetic layout
$.keypad.qwertyLayout // Standard US keyboard layout

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

$.keypad.addKeyDef(id, name, action, noHighlight) // Define an action key

$.keypad.isAlphabetic(ch) // Test for an alphabetic character
$.keypad.isNumeric(ch) // Test for a numeric character
$.keypad.toUpper(ch) // Convert character to upper case

$.keypad.insertValue(input, value) // Insert text into an input field

$(selector).keypad('option', settings) // Change instance settings
$(selector).keypad('option', name, value) // Change an instance setting
$(selector).keypad('option', name) // Retrieve an instance setting

$(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?