Layout

Sections:

Options: layout | customLayout ( Layout Keys: Action | Meta Keys | Spacers | Naming | Remapping ) | position | reposition | css
Deprecated
Contribute a layout

layout - [String]

Specify which keyboard layout to use.
'alpha' - Alphabetical layout.
'colemak' - Colemak layout.
'custom' - Uses a custom layout as defined by the customLayout option.
'dvorak' - Dvorak Simplified layout.
'international' - Standard US-international QWERTY layout.
'num' - Numerical (ten-key) layout.
'numpad' - Numerical layout with left & right caret keys (added by extender extension).
'qwerty' - Standard U.S. QWERTY layout.
Default value is 'qwerty'

customLayout - [Object]

Specify a custom layout
This was completely changed in version 1.5.3!

Setup

The layout is defined as an object with arrays.
The object is set up as a key : value pair.
The key is the name of the key set: 'normal' (no modifier), 'shift', 'alt', 'alt-shift', 'meta'.
Please note that normal is replacing default (without quotes) because it is a reserved javascript word, so if you must use it, make sure to INCLUDE quotes ('default')
The value is an array containing blocks of strings that represent a keyboard row.
Inside each block are the defined keys, which must be separated from each other with a space.
The keys are added from top to bottom and left to right, so set it up appropriately.
Regular keys should be a single character or unicode string (e.g. \u2190 = left arrow).

Special action keys have curly brackets {a} around them.

// two row keyboard
layout : 'custom',
customLayout: { 'normal': ['r o w 1 {c}', 'r o w 2 {a}'] }
// example: four rows; no shift/alt key sets
layout : 'custom',
customLayout: { 'normal': ['r o w 1', 'r o w 2', 'r o w 3', '{accept} {cancel}'] }

The default key set is shown above and must be defined in every custom layout.

To add additional key sets (e.g. 'shift') copy the same pattern as the default definition:

// two rows; each row has four key sets. An {accept} or {check}, {shift} and {alt}
// key are required.
layout : 'custom',
customLayout: {
  'normal' : ['r o w 1 {shift}', 'r o w 2 {a} {c}'],
  'shift'  : ['R O W 1 {shift}', 'R O W 2 {a} {c}']
}
// example: three rows and three key sets - shift & meta1 keyset rows included
// note: the {shift} needs to be included in both the default and shifted keysets,
// that's why there are two
layout : 'custom',
customLayout: {
  'normal' : ['a b c d e', 'f g h i j', '{shift} {meta1} {a} {c}'],
  'shift'  : ['A B C D E', 'F G H I J', '{shift} {meta1} {a} {c}'],
  'meta1'  : ['1 2 3 4 5', '6 7 8 9 0', '{shift} {meta1} {a} {c}']
}

Layout keys

Action

In the list below where two special ("Action") keys are shown, both keys have the same action but different appearances.
You can define your own key functions by adding the action key name to the $.keyboard.keyaction variable.
Default special ("Action") keys include:

Key	Description
`{a}` or `{accept}`	Updates element value and closes keyboard.
`{alt}` or `{altgr}`	AltGr for International keyboard which switches the key set. Required for alt keysets.
`{b}` or `{bksp}`	Backspace. Deletes characters to the left of the caret.
`{c}` or `{cancel}`	Clears changes and closes keyboard (clicking outside or hitting escape does this as well).
`{clear}`	Clear input window - used in num pad.
`{combo}`	Toggle combo (diacritic) key.
`{dec}`	Decimal for numeric entry, only allows one decimal point in the window (meant for use in num pad).
`{del}`	Delete. Deletes characters to the right of the caret.
`{default}`	DEPRECATED! Changes the keyset back to the original set (i.e. "normal" or "default" keyset) - the use of "default" is deprecated because it is a reserved javascript word.
`{e}` or `{enter}`	Enter/New Line. Mostly for textareas, but Shift + Enter will accept and close in an input.
`{empty}` or `{empty:#}`	Empty (blank) key. Include a numerical value to set the width of the key (behaves the same as `{sp:#}`).
`{left}`	Adds a left arrow key which moves the caret left within the input.
`{lock}`	Adds a cap lock key. The state of this key is not 100% reliable.
`{meta1}`, `{meta2}` ... `{meta#}`	Meta keys that change the key set. There is no limit on the number of meta sets that can be included in a layout. In v1.26.8, meta keys can now be named without numbers, e.g. `meta-specials` or `meta_symbolic_alphabet`; the key must always start with "meta" in the name.
`{next}`	Switch to next keyboard input/textarea.
`{normal}`	Changes the keyset back to the original (i.e. "normal" or "default" keyset).
`{prev}`	Switch to previous keyboard input/textarea.
`{right}`	Adds a right arrow key which move the caret right within the input.
`{s}` or `{shift}`	Shift/Capslock. Required to show shifted keysets.
`{sign}`	Change sign of numeric entry (positive or negative).
`{sp:#}`	Replace # with a numerical `em` value. This adds a blank space in the keyboard. A value of 1 is approximately the width of one key (which is actually 2em).
`{space}`	The Spacebar.
`{t}` or `{tab}`	Tab.
`{toggle}`	Enable or disable the keyboard.

* Note: The single letter alternative (e.g. {a} instead of {accept}) is the narrow version of the same key as defined by the display option.

Spacers

{sp:#}:
- In verisons prior to 1.9.9, a span of zero dimensions with a side margin of #em was added, i.e. {sp:1} would add a "margin: 0 1em" which adds 1em to the left and right making it 2em wide.
- Because newer versions of Firefox do not seem to render a zero dimension span at all, the plugin now sets the span width.
- A {sp:1} setting now becomes a span of "2em" width, to keep this consistent with the way this method worked previously.
- In case this causes problems, one additional change was made so the space can now be set using pixels: {sp:20px} which makes the width 20 pixels.
- Additionally, non-western formats are now supported. Using {sp:1,5} or {sp:1,5em} will set the span to 3em's in width.
```
// examples supported in version 1.9.9+; showing set widths
// 1em     2em    2.2em    2.6em    4em      2.4em      10px
'{sp:.5} {sp:1} {sp:1.1} {sp:1,3} {sp:2em} {sp:1,2em} {sp:10px}'
```
{empty}:
- This {empty} special key inserts a blank unclickable key into the keyboard. Using {sp:1} does not add a key, but a blank space between keys.
- Added in version 1.17.0.
{empty:#}
- The empty can also include a width using the same method as the {sp:#} settings.
- Added in v1.18.3.

Naming

As of version 1.5.4, all keys can be assigned a name (text put into the title attribute).
If a tooltip plugin is used on the page, just target '.ui-keyboard-button' and get the tooltip from the title.
Keys defined in the display option follow this format "Key Name:Key's Label". The "Key Name" is what is actually shown on the virtual keyboard, while "Key's Label" is added to the key's title attribute. The "Key's Label" can include spaces.
```
display: {
  'accept' : 'Accept:Accept the Content',
  'meta1'  : '\u2666:Alternate character set',  // Diamond
  'meta_2' : '\u2665:Some other character set', // Heart
}
```
The key names defined in the customLayout cannot include spaces, the script will assume you want a new key. So only in the customLayout follow this format "key:Key_Label" - replace all spaces with an underscore. Here is an example:
```
customLayout: {
  'normal' : [
    '! @:this_is_an_at_symbol # $ % ^ & *:this_is_an_asterisk ( ) - + {bksp}'
  ]
}
```
View demo.js source for more examples; look for it in the Meta demo.

Remap

Keys can be remapped so that when the user inputs a value from a physical keyboard, it remaps to a value in the virtual keyboard.
For example, pressing the a key on a physical QWERTY keyboard will activate and enter a greek letter alpha α in the input/textarea. See the main demo "Custom: Mapped Keys" example.

This can be accomplished in two different ways:

Within the custom layout add the physical keyboard key to remap after the virtual key within parentheses
```
'\u03b1(a)' // typing "a" on physical keyboard enters "α" into input/textarea
```
A tooltip can also be included by adding a colon followed by the tooltip text using an underscore in place of any spaces
```
// typing "a" on physical keyboard enters "α" into input/textarea
// hovering over the key will show a tooltip of "lower case alpha (type a)"
'\u03b1(a):lower_case_alpha_(type_a)'
```
this method can be tedious and make the layout more difficult to read.

Use the beforeInsert callback function (added in v1.26.0) to intercept and replace the value that is typed in by the user using either the physical or virtual keyboard. See this example.

$(function() {
  var remapGreek = {
    // use key: value pairs to remap the keys
    "A": "Α", "B": "Β", "D": "Δ", "E": "Ε", "H": "Η", "I": "Ι",
    "K": "Κ", "L": "Λ", "M": "Μ", "N": "Ν", "O": "Ο", "P": "Π",
    "R": "Ρ", "S": "Σ", "T": "Τ", "X": "Χ", "Y": "Υ", "Z": "Ζ",
    "F": "Φ", "G": "Γ", "J": "Ξ", "C": "Ψ", "V": "Ω", "U": "Θ",

    "a": "α", "b": "β", "d": "δ", "e": "ε", "h": "η", "i": "ι",
    "k": "κ", "l": "λ", "m": "μ", "n": "ν", "o": "ο", "p": "π",
    "r": "ρ", "s": "σ", "t": "τ", "x": "χ", "y": "υ", "z": "ζ",
    "f": "φ", "g": "γ", "j": "ξ", "c": "ψ", "v": "ω", "u": "θ"
  };

  jQuery.keyboard.layouts['Greek-custom'] = {
    "lang": ["el"],
    // Greek
    "normal": [
      "\\ 1 2 3 4 5 6 7 8 9 0 ' ] {bksp}",
      "{tab} : w ε ρ τ υ θ ι ο π + }",
      "α σ δ φ γ η ξ κ λ \u0384 \u00A8 # {enter}",
      "{shift} < ζ χ ψ ω β ν μ , . - {shift}",
      "{accept} {alt} {space} {alt} {cancel}"
    ],
    "shift": [
      "| ! \" # $ % & / ( ) = ? [ {bksp}",
      "{tab} ; W Ε Ρ Τ Υ Θ Ι Ο Π + }",
      "Α Σ Δ Φ Γ Η Ξ Κ Λ \u00A8 \u0385 @ {enter}",
      "{shift} < Ζ Χ Ψ Ω Β Ν Μ ; : _ {shift}",
      "{accept} {alt} {space} {alt} {cancel}"
    ],
    // latin characters
    "alt": [
      "\\ 1 2 3 4 5 6 7 8 9 0 ' ] {bksp}",
      "{tab} q w e r t y u i o p + }",
      "a s d f g h j k l \u0384 \u00A8 # {enter}",
      "{shift} < z x c v b n m , . - {shift}",
      "{accept} {alt} {space} {alt} {cancel}"
    ],
    "alt-shift" : [
      "| ! \" # $ % & / ( ) = ? [ {bksp}",
      "{tab} Q W E R T Y U I O P * {",
      "A S D F G H J K L \u00A8 \u0385 @ {enter}",
      "{shift} > Z X C V B N M ; : _ {shift}",
      "{accept} {alt} {space} {alt} {cancel}"
    ]
  };

  $('#keyboard').keyboard({
    layout: 'Greek-custom',
    beforeInsert: function(e, keyboard, el, textToAdd) {
      return keyboard.altActive ?
        // don't remap if alt is active
        textToAdd :
        // remap at all other times, but fallback
        // for un-remapped values
        remapGreek[textToAdd] || textToAdd;
    }
  });
});

You will still need to create a custom layout to show the actual Greek characters on the virtual keyboard

position - [Object]

Set keyboard position.
The portion of the script uses the jQuery UI position utility (optional script).
If jQuery UI position utility is not loaded, this option is ignored. You will then need to position the keyboard manually. Example CSS is provided below which positions the keyboard at the bottom of the screen.
Set this option to false to ignore the position utility, even if it is loaded.

Adjust where the keyboard pops up relative to the input area.

position : {
  // null (attach to input/textarea) or a jQuery object (attach elsewhere)
  of : null,
  my : 'center top',
  at : 'center top',
  // at2 is used when "usePreview" is false (centers keyboard at the bottom
  // of the input/textarea)
  at2: 'center bottom',
  collision: 'flipfit flipfit'
}

of refers to an object (selector, element or jQuery object) where the keyboard attaches.

The default below is null, but it reverts to the input object. Add a jQuery object (e.g. $('#keyboard-anchor')) to attach the keyboard elsewhere. This method works well for a single keyboard target.

If there are multiple keyboard targets, $('.targets') would not work as the position utility would target the first element in that jQuery object (equivalent to $('.targets:first')). So an alternate method was devised where the target object is stored in the element data variable keyboardPosition. For example, multiple hidden inputs have a keyboard link:

HTML

<a href="#" class="keyboard-links">Hidden input</a>
<!-- DON'T use type="hidden" because IE doesn't like hidden inputs -->
<input id="hidden" type="text" style="display:none;" />

Script

$('.keyboard-links').click(function(){
  $(this).next()                    // input is after the link, so use .next()
    .data('keyboardPosition', this) // store link object for keyboard positioning
    .trigger('focus');              // open keyboard
  return false;                     // disable link
});
// Don't define the position property when the keyboard is initialized
$('.keyboard').keyboard({
  layout: 'qwerty',
  accepted: function(e, keyboard, el){
    alert('The content "' + el.value + '" was accepted!');
  }
});

my (string) refers to a keyboard location. 'center top' is the keyboard point that is attached to the at element location.
at (string) refers to the element location (the input or textbox). 'center top' is the element point where the keypoint point is attached.
at2 (string) is used when the usePreview option is false. The preview window is removed and all input goes directly into the original input/textarea. The reason this is separate is that the usePreview option can be changed dynamically.
collision (string) value repositions the object when the positioned element overflows the window in some direction, it moves it to an alternative position. Similar to my and at, this accepts a single value or a pair for horizontal/vertical, eg. "flip", "fit", "fit flip", "fit none".
~~offset (string) values are added to the left-top values to the calculated position, eg. "50 50" (left top) A single value such as "50" will apply to both~~ removed from the jQuery UI position utility.
For more information see the jQuery UI position utility documents.
The default settings are shown above.

If you don't want to use jQuery UI's position utility, this css will place the keyboard at the bottom of the page (demo)

/* position keyboard at bottom of the screen */
.ui-keyboard {
  border-radius: 0;
  left: 0;
  top: auto;
  bottom: 0;
  position: fixed;
  width: 100%;
}

reposition - [Boolean]

Allow jQuery UI position utility to reposition the keyboard on window resize.
In v1.26.20, when true this option will allow the repositioning of the keyboard on keyset change (see issue #547).
This only applies if the postion option is not false and the jQuery UI position utility is included on the page.
Default setting is true.

css - [Object]

Class names used for theming.
By default, this option contains the class names needed to apply a jQuery UI theme to the keyboard.
Because of the methods used by the jQuery Mobile theme, it would be best to either clear out all of these class names, or just not load the jQuery UI stylesheet on mobile devices. Please see the Mobile extension demo source for more details.

The default values are as follows:

css : {
  // input & preview styles
  input          : 'ui-widget-content ui-corner-all',
  // keyboard container - this wraps the preview area (if `usePreview` is true)
  // and all keys
  container      : 'ui-widget-content ui-widget ui-corner-all ui-helper-clearfix',
  // keyboard container extra class (same as container, but separate)
  popup          : '',
  // default keyboard button state, these are applied to all keys, the remaining
  // css options are toggled as needed
  buttonDefault  : 'ui-state-default ui-corner-all',
  // hovered button
  buttonHover    : 'ui-state-hover',
  // Action keys (e.g. Accept, Cancel, Tab, etc); replaces the "actionClass" option
  buttonAction   : 'ui-state-active',
  // Active keys (e.g. shift down, meta keyset active, combo keys active)
  buttonActive   : 'ui-state-active',
  // used when disabling the decimal button {dec} when a decimal exists in the
  // input area
  buttonDisabled : 'ui-state-disabled',
  // empty button class name {empty}
  buttonEmpty    : 'ui-keyboard-empty'
},

Deprecated

actionClass - [String]

Class name used to make keys a different color
This variable contains the class that is only added to the Accept and cancel buttons to give them a different color from the normal keys.
It was originally set to 'ui-state-highlight' which looks good in some themes, but not others.
This class name can also be a custom one that you set up for these keys as well.
Default is 'ui-state-active'.
This option has been replaced by buttonAction within the css option.

Contribute a layout

If you would like to contribute a layout to this project, please check out the Contributing page for more details.

Home
Installation
FAQ
Setup
Usage
Options
- Layout
- Language
- Usability
- Actions
Extensions
- AltKeysPopup
- Autocomplete
- Caret
- Extender
- Mobile
- Navigation
- PreviewKeySet
- Scramble
- Typing
Methods
Contenteditable
Theme
Contributing
Log

Provide feedback

Saved searches

Use saved searches to filter your results more quickly