Let's face it: the keyboard is a constant source of pain and frustration for users and developers. Much of this has to do with the limited control browsers provide with keyboards. For native apps, we've even gone as far as creating plugins to help ease the pain of keyboards. Thankfully, browser vendors have agreed that the keyboard experience on the web is less than ideal and have decided to do something about it. In this blog post, we’ll look at some new APIs available on the web and discuss how we're using them in Ionic to help developers.

Customizing the keyboard

If you think of a standard mobile keyboard, there are probably a few different layouts that come to mind. You have your standard text-based keyboard and one for telephone numbers. Well what if I told you that there are more keyboards than that but have not really been available to web developers?

For example, there's a specific keyboard available for helping users type an email address. There's also a keyboard that provides specific keys when entering text into a search bar. Want the layout of a tel input but just for regular numbers? There's a keyboard for that as well. There are many more examples of this, but the point is, these keyboards have not been something web developers could control or opt into. Thankfully, we can leverage inputmode and enterkeyhint to help tell the keyboard how to behave.

• inputmode

The inputmode attribute allows developers to specify what type of data might be entered into an input. This will tell the browser to show a keyboard that includes keys relevant to what the user may enter. For example, inputmode="email" will display a keyboard with the @ key as well as other optimizations for entering emails.

Inputs that require a certain data type should use the type attribute instead. For example, inputs that require an email should use type="email" rather than specifying an inputmode. This is because the data that will be entered is always going to be in the form of an email. On the other hand, if the input accepts an email or a username, using inputmode=”email” is appropriate because the data being entered is not always going to be an email address.

Here is an example of using inputmode:

<ion-item>
  <ion-label>To: </ion-label>
  <ion-input inputmode="email"></ion-input>
</ion-item>

In the example above, we have an email compose screen that lets users type in either a name or an email address of a recipient. When using inputmode="email" both iOS and Android will display an @ key as well as other email-specific keyboard optimizations.

The inputmode attribute is supported in Chrome 66+ and iOS Safari 12.2+: https://caniuse.com/#search=inputmode

• enterkeyhint

The enterkeyhint attribute allows developers to specify what type of action label or icon should be shown for the "Enter" key. Using enterkeyhint gives the user a preview of what will happen when they tap the “Enter” key. The value that should be specified here depends on the context of what the user is doing. For example, if the user is typing into a search box, developers should ensure that the input has enterkeyhint="search".

Here is an example of using enterkeyhint:

<ion-item>
  <ion-label>Message: </ion-label>
  <ion-input enterkeyhint="send"></ion-input>
</ion-item>

In the example above, we have a chat screen that lets users type and send a message. When using enterkeyhint="send", both iOS and Android will show a Send label on the "Enter" key.

The enterkeyhint attribute is supported in Chrome 77+ and iOS Safari 13.4+: HTML Spec.

Keyboard events

Aside from customizing how the keyboard looks, developers often need to confirm if the keyboard is visible or not. This functionality has traditionally been limited to native apps leveraging plugins in Capacitor or Cordova. This is where the Visual Viewport API can help.

With the introduction of the Visual Viewport API, apps running in a mobile browser or as a PWA can now detect the presence of an on-screen keyboard. This is useful for adjusting the positioning of an input that would otherwise be hidden by the keyboard.

The mobile web contains two viewports: The layout viewport and the visual viewport. The layout viewport covers all elements on a page and is the part of the page that elements with position: fixed stick to. The visual viewport is the part of the page we actually see. The visual viewport can move around when panning and zooming, even if elements with position: fixed remain where they are.

Using this API we can detect when an on-screen keyboard is presented or when a page is zoomed using a pinch-to-zoom gesture. For more information about the Visual Viewport: https://developers.google.com/web/updates/2017/09/visual-viewport-api.

Now that we can detect when a keyboard is being shown or not, we can actually provide correct events for the user! Ionic Framework v5.1 brings two new events developers can listen for: ionKeyboardDidShow and ionKeyboardDidHide.

Ionic Keyboard Events

The ionKeyboardDidShow and ionKeyboardDidHide events are dispatched from window. The ionKeyboardDidShow event includes a payload that has an approximation of the keyboard height in pixels. Developers can use that information to translate an input or scroll to an input that would otherwise have been hidden by the keyboard.

Here is an example of using the keyboard events:

const input = document.querySelector('ion-input');

window.addEventListener('ionKeyboardDidShow', (ev) => {
  const { keyboardHeight } = ev.detail;

  input.style.setProperty(
    'transform',
    `translate3d(0, ${keyboardHeight}px, 0)`
  );
});

window.addEventListener('ionKeyboardDidHide', () => {
  input.style.removeProperty('transform');
});

In the example above, we listen for the keyboard lifecycle events and translate the input according to the keyboard height.

While the Visual Viewport resize events typically do not fire in Capacitor and Cordova applications, the ionKeyboardDidShow and ionKeyboardDidHide events still fire when using the native keyboard plugin.

Ionic Keyboard Events are supported in Chrome 62+ and iOS Safari 13.0+.

Trying it out

These keyboard improvements are part of the framework’s 5.1 release. Our goal for these features is to make it easier than ever to customize and account for on-screen keyboards and greatly improve the user experience of your applications.

To get started with keyboard customization, checkout some of the MDN and HTML Spec links to learn more about inputmode and enterkeyhint. We'll be rolling our our own docs in the coming weeks, and will update this post with a reference to them.

We encourage anyone to file bugs or feature requests on our GitHub Issue Tracker.

• inputmode spec page
• enterkeyhint spec page
• Visual Viewport MDN docs