Usability

initialized, beforeVisible, visible, change, beforeClose, accepted, canceled, restricted, hidden or validate [Function]

Callback function called.
See the Methods page for more details.

acceptValid - [Boolean]

Continually check input against the validate function.
When true, the current input will be checked using the validate function after each input.
- If the input is valid, the accept button will be clickable.
- If the input is not valid, the accept button is disabled.
When false, the input will not be checked until the input is accepted.
Default is false.

activeOnReadonly - [Boolean]

Displays the keyboard even when the input is readonly.
Default is false.

alwaysOpen - [Boolean]

Keyboard will always remain visible.
When true, the keyboard will automatically open on page load and remain open, even after clicking accept or hitting the escape key.
When false, the keyboard will behave as it does normally. It opens when the input/textarea has focus and closes when focus is lost or the escape key, accept or cancel button is pressed.
Default is false.

appendLocally - [Boolean]

Append the keyboard locally (next to the input), so tabNavigation will work.
When false, the virtual keyboard is appended to the the target of the appendTo option (default is the body of the page). This allows it to be free of any constraints placed on the input.
When true, the virtual keyboard is added after the input it is applied to. This has the following consequences:
- An advantage of this would be that the virtual keyboard's preview input is kept in line with the input it is attached to, so setting tabNavigation to true, allows you to press tab and get to the next input/textarea. If the keyboard was appended to the body of the page, pressing tab would move the focus up to the browser location window.
- Another advantage would be that the styling of a keyboard attached locally could be changed, using css, to appear different from other keyboards. This doesn't work so well if you want to use completely different jQuery UI themes, but you can target the virtual keyboard uniquely using css.
- A disadvantage of this setting would be that any layout restrictions applied to the original input's container would be applied to the virtual keyboard. For example, the index.html demo page has each example wrapped in a div with a width of 262 pixels. The keyboard that is appended locally will also have it's width limited to this value and as Mr. Horse would say, "No sir, I don't like it".
Default is false.

appendTo - [String] or [Object]

Append the keyboard to whatever element you want.
When the appendLocally option is false, the virtual keyboard is appended to the body of the page by default.
Set this option to use a jQuery string selector ("body") or jQuery object ($("body")) as desired.
Default is "body".

autoAccept - [Boolean]

Auto-accept content when clicking outside the keyboard (popup will close).
When set to false, clicking outside the keyboard will close and ignore the content in the preview window.
If true, clicking outside the keyboard or pressing escape will close the keyboard and accept the content from the preview window.
Default is false.

autoAcceptOnEsc - [Boolean]

Auto-accept content even if the user presses escape.
This option only works if autoAccept is true.
Default is false.

autoAcceptOnValid - [Boolean]

Auto-accept content when input is valid
This option requires
- acceptValid option set to true
- validate callback
Default is false.

cancelClose - [Boolean]

This option only works with acceptValid is true and the validate function returns false.
If true, this option will cancel the keyboard close initiated by the accept button. The keyboard can still be closed by pressing escape or the cancel button.
If false, the validate function will ignore the user input, restore the input's previous value, and close the keyboard.
Default is true.

caretToEnd - [Boolean]

Positions the caret at the end of any text within the input when keyboard becomes visible.
When false, the caret should position at the caret location matching where the user clicked in the input/textarea, e.g. if "Waffles" is in the input, and the user clicks between the two f's, the keyboard will open and position the caret between the two f's in the preview window; at least in most modern browsers.
When true, the caret will always be positioned at the end when the keyboard becomes visible.
Default is false.

checkValidOnInit - [Boolean]

When true, the validate function is called to check the content and set the "accept" button state.
When false, the validate function is not called and the "accept" button state is not set. It will get set once the user begins interacting with the keyboard.

closeByClickEvent - [Boolean]

Allows the user to scroll the page without closing the keyboard.
If true the keyboard can only be closed on click event instead of mousedown or touchstart (default); or closed by targeting another input or textarea.
If false the keyboard will close on touchstart or mousedown (if the userClosed option isn't set).
Default is false.

combos [Object]

Not listed in the above options, but you can add more if you wish.
The full set of combinations are not intended to be changed so they were not listed in the options above.
But you can add more key combinations as desired by using this format (try it in any of the demos, except the Custom: Hex - we don't want have ligatures there).
```
combos : {
  'a' : { e: '\u00e6' },
  'A' : { E: '\u00c6' }
}
```
In the default settings the root key is a diacritic ( `, ', ", ^, ~ ) and the script is only setup to accept these. And also the 'a' so the example above will work if you try it.
To use different diacritics the regex in the $.keyboard.comboRegex variable will need to be modified. If you don't know how to do this, then please add an issue and we will look into adding it.
Note that even though these special characters are included in this plugin they may not be visible in all browsers. They may need to be set to the proper encoding (e.g. UTF-8, ISO-8859, etc).
Here is an example on now to change <3 into a heart.
- There are two ways to modify the regex:
  - You can change $.keyboard.comboRegex BEFORE initializing the keyboard because it stores the current regex. All subsequent keyboards will be effected by this change.
```
// "<" added to the beginning of the default regex
$.keyboard.comboRegex = /([<`\'~\^\"ao])([a-z])/mig;
```
    ( Note: the formatting of the above regex may be malformed by the syntax highlighter, you should see $.keyboard.comboRegex = /([<`\'~^"ao])([a-z])/mig; )
  - If you only want the regex applied to this particular keyboard, then change the regex afterwards in the initialization callback
```
$('#keyboard').keyboard({
  initialized : function(e, keyboard, el){
    // "<" added to the beginning of the default regex
    keyboard.regex = /([<`\'~\^\"ao])([a-z3])/mig;
  },
  combos : {
    '<' : { 3:"\u2665" } // turn <3 into a heart
  }
});
```
    ( Note: the formatting of the above regex may be malformed by the syntax highlighter, you should see keyboard.regex = /([<`'~^"ao])([a-z3])/mig; )
  - If you look close at the regex definitions above, the < was added to the beginning of the first portion of the regex and a 3 was added to the second portion:
```
//                       ([first part])([2nd])
$.keyboard.comboRegex = /([`\'~\^\"ao])([a-z])/mig;  // original regex
// the first part is ([`\'~\^\"ao]), add any new accents or characters inside of the square brackets
// the second part is ([a-z]), add any new characters inside the square brackets;
// to include all numbers add `\d` inside the square brackets.
```
    ( Note: the formatting of the above regex may be malformed by the syntax highlighter, you should see $.keyboard.comboRegex = /([`'~^"ao])([a-z])/mig; // original regex )
- Then you just need to define the combo '<' : { 3:"\u2665" } in the combos option when initializing the plugin (see above).

Here is another example on how to replace the apostrophe (') with an acute accent (´) - see issue #133.

// Add acute accent combos
$.extend(true, $.keyboard.defaultOptions.combos, {
  "\u00b4" : { a:"\u00e1", A:"\u00c1", e:"\u00e9", E:"\u00c9", i:"\u00ed", I:"\u00cd", o:"\u00f3", O:"\u00d3", u:"\u00fa", U:"\u00da", y:"\u00fd", Y:"\u00dd" } // acute
});
// update the accent regex to remove the apostrophe and add the acute accent
$.keyboard.comboRegex = /([`~\^\"ao\u00b4])([a-z])/mig;
// remove the apostrophe combos - this isn't really needed because the apostrophe isn't
// in the regex anymore, but added here for completeness
delete $.keyboard.defaultOptions.combos["'"];

( Note: the formatting of the above regex may be malformed by the syntax highlighter, you should see $.keyboard.comboRegex = /([`~^"ao\u00b4])([a-z])/mig; )

enterMod - [String]

Key pressed to go to the previous input/textarea.
Mod key options: 'ctrlKey', 'shiftKey', 'altKey', 'metaKey' (MAC only).
For example, if this option is 'altKey', "alt-enter" will switch to the previous input/textarea and "shift-alt-enter" will accept & go to previous input/textarea.
Default is 'altKey'.

enterNavigation - [Boolean]

Press enter (shift-enter in textarea) to go to the next input field.
When false, pressing enter do nothing in an input and shift to the next line in a textarea.
When true, pressing enter (shift-enter in textarea) on either the real or virtual keyboard will shift focus to the next input with a keyboard attached. I am considering changing this to the next input ( with or without a keyboard attached ).
Default is true.

ignoreEsc - [Boolean]

When true, escape does not close the keyboard.
Default is false.

initialFocus - [Boolean]

When a keyboard is initially open, the input will get focus when this option is set to true.
If set to false, focus will not be applied to the input. The user will need to manually click inside the input to begin manual typing; but clicking on the virtual keyboard will enter and give focus to the input.
If chaining multiple inputs:
- Set this option to false, then add a "keyboard-init-focus" class to the input which is to get the initial focus.
- See phone number or serial number demo.
- Use $.keyboard.css.initialFocus = "keyboard-init-focus"; to alter the class name.

keyBinding - [String]

Mouse event used to interact with the key.
This is the event type that the script binds to the key.
Possible options include 'mouseup', 'mousedown' and 'click'. Using an event like 'mouseenter' may get a little messy.
Default is 'mousedown touchstart'.

lockInput - [Boolean]

Prevent access to the preview window from outside of the virtual keyboard.
When set to false, the user can type and edit in the preview window.
If true:
- The user will only be able to add characters to the preview window using the virtual keyboard.
- Setting the caret within the preview is still possible.
- Demo.
Default is false.

maxInsert - [Boolean]

Allow inserting characters at caret when maxLength value is set.
Default is true.

maxLength - [Boolean/Number]

Set a maximum length to the content.
When set to false, there is no maximum length to the input.
If maxLength is a number, then the content is limited to that length.
Default is false.

noFocus - [Boolean]

Avoid focusing the input the keyboard is attached to if set to true.
The hardware keyboard will generally not work when this is used. Setting lockInput to true is recommended for best results.

Used with lockInput and an onfocus handler that blurs the input, this can help avoid the built-in keyboard popping up at all on touch devices.

$('#demo_without_preview')
    .on('focus',function(){ this.blur(); })
    .keyboard({
        lockInput: true,
        noFocus: true,
        usePreview: false
    })
    .addCaret();
$('#demo_with_preview')
    .on('focus',function(){ this.blur(); })
    .keyboard({
        lockInput: true,
        noFocus: true,
        visible: function(evt,kb){
            kb.$preview.on('focus',function(){ this.blur(); });
        }
    })
    .addCaret();

openOn - [String]

Event used to open the keyboard.
This string contains the event(s) that open the keyboard.
To disable this, set this value to an empty string "".
Default is focus.

preventDoubleEventTime [Number]

Time in milliseconds (ms) to ignore an event after a previously fired event in case a "similar" event is fired more than once, e.g. a touchstart and mousedown firing on the same key.
Set this value to a low number (maybe less than 300 ms) to prevent skipping events from fast typers.
Default is 100 (ms).

preventPaste - [Boolean]

Prevents pasting content into the input/textarea by either (ctrl-v) or the right-click menu.
When set to false, the user can paste content into the input/textarea.
If true, then the user can not right click or open the context menu on the input/textarea, nor can they type in Ctrl-V to paste content into the area.
Default is false.

repeatDelay - [Number]

Time to pause before starting key repeat.
The value is the time in milliseconds to pause before starting a key repeat.
This repeat was added to the virtual keyboard to emulate a real keyboard key repeat. When clicking down or touching (touch devices) a virtual keyboard button the key will repeat.
Without this ability, each click or touch on the virtual keyboard would only add one character to the input.
The default value is 500 (milliseconds).

repeatRate - [Number]

Rate (characters per second) at which to repeat keys.
Setting this value to 0 (zero) will disable the key repeat that occurs only while clicking on a virtual keyboard key.
This value, represented as characters per second (cps), is the rate at which characters are added to the input area while holding down a virtual keyboard button.
The repeated keys starts after the initial repeatDelay.
This rate is very dependent on the speed of javascript in the particular browser being used. In Firefox, it appears that the upper rate limit is around 20 cps, in that any values above that don't appear to increase the speed of the repeat. I'm sure Chrome will have a much higher rate and older IE will be much lower.
The default value is 20 (cps).

resetDefault - [Boolean]

When true the keyboard will reset so that the default keyset is visible when the keyboard opens.
Previously, the last keyset the user changes to will reappear.
Default value is false.

restrictInclude - [String]

Additional list of characters or words that will be allowed when the restrictInput option is true.
For example, the main demo hex input keyset only shows 0-9 and "A" to "F". This option is used to include lower case "a" to "f".
Add as a string of space-separated values: e.g. 'a b foo \ud83d\ude38'.
In version 1.27.1, you can include a space in this string, by using a {space} placeholder, e.g. 'a {space} b'.
Default is '' (empty string).

restrictInput - [Boolean]

Prevents keys not in the displayed keyboard from being typed in the input area.
When set to false, the user can click inside the input area and type or paste in any text.
If true, when the user types or pastes in any keys not found in the virtual keyboard, those characters will be removed.
Default is false.

scrollAdjustment - [Number/String]

When using virtual keys that cause an input to scroll, if this value is a number, the caret position is set at this number of pixels from the inner edge of the input.
If this option is set to 'c', then the caret will cause the input to scroll from the center of the input.
Setting this option to zero (0) may make the caret not visible as it will be under the input border.
Default is 10 (pixels).

stayOpen - [Boolean]

Keyboard remains open when input loses focus.
When true, the keyboard will not automatically close when the input loses focus. It will close when another keyboard is opened or if the user presses accept, cancel or escape.
If false, the keyboard will automatically close when the input loses focus, or the user presses accept, cancel or escape.
Default is false.

stickyShift - [Boolean]

Shift key stays active until it is clicked again.
When false, the shift key will remain active until the next key is (mouse) clicked on.
If true, the shift will stay active until pressed again.
Default is true.

stopAtEnd - [Boolean]

Toggles wrapping to the first or last element when the default switch input function is used.
If true, the next button will stop on the last keyboard input/textarea; prev button stops at first.
If false, the next button will wrap to target the first input/textarea; prev will go to the last.
Default is true.

tabNavigation - [Boolean]

Allows using the tab key to navigate to the next input/textarea.
When false, tab keys inside of an input will be ignored and the tab key inside of a textarea will add a tab to that area.
When true, using the tab key inside of an input will shift focus from the current input to the next input/textarea. Or previous input/textarea if you use Shift-Tab. The tab inside of a textarea should still add a tab inside of the area.
Default is false.

useCombos [Boolean]

Allows users to type in key combos to add characters with diacritics.
If true, the script will automatically convert key combinations into diacritics characters.
If false, the script will ignore the triggering key combinations.
This is an automatic feature on international keyboards ([dead keys][6]), so the script is only emulating the same function.
Default is true.

usePreview - [Boolean]

Include a preview input or use the original.
When true, a preview input (clone of the original input) will be included above the virtual keyboard and the entire keyboard will overlay the original input (if the default position is used).
When false, the keyboard will position itself under the original input, if the default positioning is used, so the user is typing directly into the original input.
Default is true.

useWheel [Boolean]

Allows the enabling or disabling of mousewheel functionality.
If false, the mousewheel will have no apparent function, and any associated code will not be active.
If true, if the user scrolls the mousewheel over a virtual key, keys values in the same position in other keysets will be visible & usable.
Even if this option is set to true, it still depends on the existence of the mousewheel plugin.
Default is true.

userClosed [Boolean]

Prevents the keyboard from closing when the user clicks or presses outside the keyboard.
When true the keyboard will close when the user presses "Accept", "Cancel" or hits the Esc key.
When false clicking or pressing outside the keyboard will cause it to close.
This option is useful if the user needs to scroll the page using a mouse or touch event, or if multiple keyboards are in use.
Note: that the autoAccept option must be set to true or the keyboard will close and changes will be lost.

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