chrome.input.ime

Description: Use the chrome.input.ime API to implement a custom IME for Chrome OS. This allows your extension to handle keystrokes, set the composition, and manage the candidate window.
Availability: Since Chrome 35.
Permissions: "input"

Manifest

You must declare the "input" permission in the extension manifest to use the input.ime API. For example:

      {
        "name": "My extension",
        ...
        "permissions": [
          "input"
        ],
        ...
      }

Examples

The following code creates an IME that converts typed letters to upper case.

      var context_id = -1;
      
      chrome.input.ime.onFocus.addListener(function(context) {
        context_id = context.contextID;
      });
      
      chrome.input.ime.onKeyEvent.addListener(
        function(engineID, keyData) {
          if (keyData.type == "keydown" && keyData.key.match(/^[a-z]$/)) {
            chrome.input.ime.commitText({"contextID": context_id,
                                         "text": keyData.key.toUpperCase()});
            return true;
          } else {
            return false;
          }
        });
      

For an example of using this API, see the basic input.ime sample. For other examples and for help in viewing the source code, see Samples.

Summary

Types
KeyboardEventType
KeyboardEvent
InputContextType
AutoCapitalizeType
InputContext
MenuItemStyle
MenuItem
UnderlineStyle
WindowPosition
ScreenType
MouseButton
AssistiveWindowType
AssistiveWindowProperties
AssistiveWindowButton
Methods
setComposition chrome.input.ime.setComposition(object parameters, function callback)
clearComposition chrome.input.ime.clearComposition(object parameters, function callback)
commitText chrome.input.ime.commitText(object parameters, function callback)
sendKeyEvents chrome.input.ime.sendKeyEvents(object parameters, function callback)
hideInputView chrome.input.ime.hideInputView()
setCandidateWindowProperties chrome.input.ime.setCandidateWindowProperties(object parameters, function callback)
setCandidates chrome.input.ime.setCandidates(object parameters, function callback)
setCursorPosition chrome.input.ime.setCursorPosition(object parameters, function callback)
setAssistiveWindowProperties chrome.input.ime.setAssistiveWindowProperties(object parameters, function callback)
setAssistiveWindowButtonHighlighted chrome.input.ime.setAssistiveWindowButtonHighlighted(object parameters, function callback)
setMenuItems chrome.input.ime.setMenuItems(object parameters, function callback)
updateMenuItems chrome.input.ime.updateMenuItems(object parameters, function callback)
deleteSurroundingText chrome.input.ime.deleteSurroundingText(object parameters, function callback)
keyEventHandled chrome.input.ime.keyEventHandled(string requestId, boolean response)
Events
onActivate
onDeactivated
onFocus
onBlur
onInputContextUpdate
onKeyEvent
onCandidateClicked
onMenuItemActivated
onSurroundingTextChanged
onReset
onAssistiveWindowButtonClicked

Types

KeyboardEventType

Enum
"keyup", or "keydown"

KeyboardEvent

See http://www.w3.org/TR/DOM-Level-3-Events/#events-KeyboardEvent
properties
KeyboardEventType type

One of keyup or keydown.

string (optional) requestId

(Deprecated) The ID of the request. Use the requestId param from the onKeyEvent event instead.

string (optional) extensionId

The extension ID of the sender of this keyevent.

string key

Value of the key being pressed

string code

Value of the physical key being pressed. The value is not affected by current keyboard layout or modifier state.

integer (optional) keyCode

Since Chrome 37.

The deprecated HTML keyCode, which is system- and implementation-dependent numerical code signifying the unmodified identifier associated with the key pressed.

boolean (optional) altKey

Whether or not the ALT key is pressed.

boolean (optional) altgrKey

Since Chrome 79.

Whether or not the ALTGR key is pressed.

boolean (optional) ctrlKey

Whether or not the CTRL key is pressed.

boolean (optional) shiftKey

Whether or not the SHIFT key is pressed.

boolean (optional) capsLock

Whether or not the CAPS_LOCK is enabled.

InputContextType

Type of value this text field edits, (Text, Number, URL, etc)
Enum
"text", "search", "tel", "url", "email", "number", "password", or "null"

AutoCapitalizeType

The auto-capitalize type of the text field.
Enum
"characters", "words", or "sentences"

InputContext

Describes an input Context
properties
integer contextID

This is used to specify targets of text field operations. This ID becomes invalid as soon as onBlur is called.

InputContextType type

Type of value this text field edits, (Text, Number, URL, etc)

boolean autoCorrect

Since Chrome 40.

Whether the text field wants auto-correct.

boolean autoComplete

Since Chrome 40.

Whether the text field wants auto-complete.

AutoCapitalizeType autoCapitalize

Since Chrome 69.

The auto-capitalize type of the text field.

boolean spellCheck

Since Chrome 40.

Whether the text field wants spell-check.

boolean shouldDoLearning

Since Chrome 68.

Whether text entered into the text field should be used to improve typing suggestions for the user.

MenuItemStyle

The type of menu item. Radio buttons between separators are considered grouped.
Enum
"check", "radio", or "separator"

MenuItem

A menu item used by an input method to interact with the user from the language menu.
properties
string id

String that will be passed to callbacks referencing this MenuItem.

string (optional) label

Text displayed in the menu for this item.

MenuItemStyle (optional) style

The type of menu item.

boolean (optional) visible

Indicates this item is visible.

boolean (optional) checked

Indicates this item should be drawn with a check.

boolean (optional) enabled

Indicates this item is enabled.

UnderlineStyle

The type of the underline to modify this segment.
Enum
"underline", "doubleUnderline", or "noUnderline"

WindowPosition

Where to display the candidate window. If set to 'cursor', the window follows the cursor. If set to 'composition', the window is locked to the beginning of the composition.
Enum
"cursor", or "composition"

ScreenType

The screen type under which the IME is activated.
Enum
"normal", "login", "lock", or "secondary-login"

MouseButton

Which mouse buttons was clicked.
Enum
"left", "middle", or "right"

AssistiveWindowType

Type of assistive window.
Enum
"undo"

AssistiveWindowProperties

Since Chrome 85. Warning: this is the current Dev channel. Learn more.

Properties of the assistive window.
properties
AssistiveWindowType type
boolean visible

Sets true to show AssistiveWindow, sets false to hide.

string (optional) announceString

Strings for ChromeVox to announce.

AssistiveWindowButton

ID of buttons in assistive window.
Enum
"undo", or "addToDictionary"

Methods

setComposition

chrome.input.ime.setComposition(object parameters, function callback)

Set the current composition. If this extension does not own the active IME, this fails.

Parameters
object parameters
integer contextID

ID of the context where the composition text will be set

string text

Text to set

integer (optional) selectionStart

Position in the text that the selection starts at.

integer (optional) selectionEnd

Position in the text that the selection ends at.

integer cursor

Position in the text of the cursor.

array of object (optional) segments

List of segments and their associated types.

Properties of each object

integer start

Index of the character to start this segment at

integer end

Index of the character to end this segment after.

UnderlineStyle style

The type of the underline to modify this segment.

function (optional) callback

Called when the operation completes with a boolean indicating if the text was accepted or not. On failure, runtime.lastError is set.

If you specify the callback parameter, it should be a function that looks like this:

function(boolean success) {...};
boolean success

clearComposition

chrome.input.ime.clearComposition(object parameters, function callback)

Clear the current composition. If this extension does not own the active IME, this fails.

Parameters
object parameters
integer contextID

ID of the context where the composition will be cleared

function (optional) callback

Called when the operation completes with a boolean indicating if the text was accepted or not. On failure, runtime.lastError is set.

If you specify the callback parameter, it should be a function that looks like this:

function(boolean success) {...};
boolean success

commitText

chrome.input.ime.commitText(object parameters, function callback)

Commits the provided text to the current input.

Parameters
object parameters
integer contextID

ID of the context where the text will be committed

string text

The text to commit

function (optional) callback

Called when the operation completes with a boolean indicating if the text was accepted or not. On failure, runtime.lastError is set.

If you specify the callback parameter, it should be a function that looks like this:

function(boolean success) {...};
boolean success

sendKeyEvents

chrome.input.ime.sendKeyEvents(object parameters, function callback)

Sends the key events. This function is expected to be used by virtual keyboards. When key(s) on a virtual keyboard is pressed by a user, this function is used to propagate that event to the system.

Parameters
object parameters
integer contextID

ID of the context where the key events will be sent, or zero to send key events to non-input field.

array of KeyboardEvent keyData

Data on the key event.

function (optional) callback

Called when the operation completes.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

hideInputView

chrome.input.ime.hideInputView()

Hides the input view window, which is popped up automatically by system. If the input view window is already hidden, this function will do nothing.

setCandidateWindowProperties

chrome.input.ime.setCandidateWindowProperties(object parameters, function callback)

Sets the properties of the candidate window. This fails if the extension doesn't own the active IME

Parameters
object parameters
string engineID

ID of the engine to set properties on.

object properties
boolean (optional) visible

True to show the Candidate window, false to hide it.

boolean (optional) cursorVisible

True to show the cursor, false to hide it.

boolean (optional) vertical

True if the candidate window should be rendered vertical, false to make it horizontal.

integer (optional) pageSize

The number of candidates to display per page.

string (optional) auxiliaryText

Text that is shown at the bottom of the candidate window.

boolean (optional) auxiliaryTextVisible

True to display the auxiliary text, false to hide it.

integer (optional) totalCandidates

Since Chrome 84.

The total number of candidates for the candidate window.

integer (optional) currentCandidateIndex

Since Chrome 84.

The index of the current chosen candidate out of total candidates.

WindowPosition (optional) windowPosition

Where to display the candidate window.

function (optional) callback

Called when the operation completes.

If you specify the callback parameter, it should be a function that looks like this:

function(boolean success) {...};
boolean success

setCandidates

chrome.input.ime.setCandidates(object parameters, function callback)

Sets the current candidate list. This fails if this extension doesn't own the active IME

Parameters
object parameters
integer contextID

ID of the context that owns the candidate window.

array of object candidates

List of candidates to show in the candidate window

Properties of each object

string candidate

The candidate

integer id

The candidate's id

integer (optional) parentId

The id to add these candidates under

string (optional) label

Short string displayed to next to the candidate, often the shortcut key or index

string (optional) annotation

Additional text describing the candidate

object (optional) usage

The usage or detail description of word.

string title

The title string of details description.

string body

The body string of detail description.

function (optional) callback

Called when the operation completes.

If you specify the callback parameter, it should be a function that looks like this:

function(boolean success) {...};
boolean success

setCursorPosition

chrome.input.ime.setCursorPosition(object parameters, function callback)

Set the position of the cursor in the candidate window. This is a no-op if this extension does not own the active IME.

Parameters
object parameters
integer contextID

ID of the context that owns the candidate window.

integer candidateID

ID of the candidate to select.

function (optional) callback

Called when the operation completes

If you specify the callback parameter, it should be a function that looks like this:

function(boolean success) {...};
boolean success

setAssistiveWindowProperties

chrome.input.ime.setAssistiveWindowProperties(object parameters, function callback)

Since Chrome 85. Warning: this is the current Dev channel. Learn more.

Shows/Hides an assistive window with the given properties.

Parameters
object parameters
integer contextID

ID of the context owning the assistive window.

AssistiveWindowProperties properties

Properties of the assistive window.

function (optional) callback

Called when the operation completes.

If you specify the callback parameter, it should be a function that looks like this:

function(boolean success) {...};
boolean success

setAssistiveWindowButtonHighlighted

chrome.input.ime.setAssistiveWindowButtonHighlighted(object parameters, function callback)

Not fully implemented. You must build Chromium from source to try this API. Learn more.

Highlights/Unhighlights a button in an assistive window.

Parameters
object parameters
integer contextID

ID of the context owning the assistive window.

AssistiveWindowButton buttonID

The ID of the button

AssistiveWindowType windowType

The window type the button belongs to.

string (optional) announceString

The text for the screenreader to announce.

boolean highlighted

Whether the button should be highlighted.

function (optional) callback

Called when the operation completes. On failure, runtime.lastError is set.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

setMenuItems

chrome.input.ime.setMenuItems(object parameters, function callback)

Adds the provided menu items to the language menu when this IME is active.

Parameters
object parameters
string engineID

ID of the engine to use

array of MenuItem items

MenuItems to add. They will be added in the order they exist in the array.

function (optional) callback

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

updateMenuItems

chrome.input.ime.updateMenuItems(object parameters, function callback)

Updates the state of the MenuItems specified

Parameters
object parameters
string engineID

ID of the engine to use

array of MenuItem items

Array of MenuItems to update

function (optional) callback

Called when the operation completes

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

deleteSurroundingText

chrome.input.ime.deleteSurroundingText(object parameters, function callback)

Deletes the text around the caret.

Parameters
object parameters
string engineID

ID of the engine receiving the event.

integer contextID

ID of the context where the surrounding text will be deleted.

integer offset

The offset from the caret position where deletion will start. This value can be negative.

integer length

The number of characters to be deleted

function (optional) callback

Called when the operation completes.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

keyEventHandled

chrome.input.ime.keyEventHandled(string requestId, boolean response)

Indicates that the key event received by onKeyEvent is handled. This should only be called if the onKeyEvent listener is asynchronous.

Parameters
string requestId

Request id of the event that was handled. This should come from keyEvent.requestId

boolean response

True if the keystroke was handled, false if not

Events

onActivate

This event is sent when an IME is activated. It signals that the IME will be receiving onKeyPress events.

addListener

chrome.input.ime.onActivate.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function(string engineID, ScreenType screen) {...};
string engineID

ID of the engine receiving the event

ScreenType screen

Since Chrome 38.

The screen type under which the IME is activated.

onDeactivated

This event is sent when an IME is deactivated. It signals that the IME will no longer be receiving onKeyPress events.

addListener

chrome.input.ime.onDeactivated.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function(string engineID) {...};
string engineID

ID of the engine receiving the event

onFocus

This event is sent when focus enters a text box. It is sent to all extensions that are listening to this event, and enabled by the user.

addListener

chrome.input.ime.onFocus.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function( InputContext context) {...};
InputContext context

Describes the text field that has acquired focus.

onBlur

This event is sent when focus leaves a text box. It is sent to all extensions that are listening to this event, and enabled by the user.

addListener

chrome.input.ime.onBlur.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function(integer contextID) {...};
integer contextID

The ID of the text field that has lost focus. The ID is invalid after this call

onInputContextUpdate

This event is sent when the properties of the current InputContext change, such as the the type. It is sent to all extensions that are listening to this event, and enabled by the user.

addListener

chrome.input.ime.onInputContextUpdate.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function( InputContext context) {...};
InputContext context

An InputContext object describing the text field that has changed.

onKeyEvent

Fired when a key event is sent from the operating system. The event will be sent to the extension if this extension owns the active IME. The listener function should return true if the event was handled false if it was not. If the event will be evaluated asynchronously, this function must return undefined and the IME must later call keyEventHandled() with the result.

addListener

chrome.input.ime.onKeyEvent.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function(string engineID, KeyboardEvent keyData, string requestId) {...};
string engineID

ID of the engine receiving the event

KeyboardEvent keyData

Data on the key event

string requestId

Since Chrome 79.

ID of the request. If the event listener returns undefined, then keyEventHandled must be called later with this requestId.

onCandidateClicked

This event is sent if this extension owns the active IME.

addListener

chrome.input.ime.onCandidateClicked.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function(string engineID, integer candidateID, MouseButton button) {...};
string engineID

ID of the engine receiving the event

integer candidateID

ID of the candidate that was clicked.

MouseButton button

Which mouse buttons was clicked.

onMenuItemActivated

Called when the user selects a menu item

addListener

chrome.input.ime.onMenuItemActivated.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function(string engineID, string name) {...};
string engineID

ID of the engine receiving the event

string name

Name of the MenuItem which was activated

onSurroundingTextChanged

Called when the editable string around caret is changed or when the caret position is moved. The text length is limited to 100 characters for each back and forth direction.

addListener

chrome.input.ime.onSurroundingTextChanged.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function(string engineID, object surroundingInfo) {...};
string engineID

ID of the engine receiving the event

object surroundingInfo

The surrounding information.

string text

The text around the cursor. This is only a subset of all text in the input field.

integer focus

The ending position of the selection. This value indicates caret position if there is no selection.

integer anchor

The beginning position of the selection. This value indicates caret position if there is no selection.

integer offset

Since Chrome 46.

The offset position of text. Since text only includes a subset of text around the cursor, offset indicates the absolute position of the first character of text.

onReset

This event is sent when chrome terminates ongoing text input session.

addListener

chrome.input.ime.onReset.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function(string engineID) {...};
string engineID

ID of the engine receiving the event

onAssistiveWindowButtonClicked

Since Chrome 85. Warning: this is the current Dev channel. Learn more.

This event is sent when a button in an assistive window is clicked.

addListener

chrome.input.ime.onAssistiveWindowButtonClicked.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function(object details) {...};
object details
AssistiveWindowButton buttonID

The ID of the button clicked.

AssistiveWindowType windowType

The type of the assistive window.