Illustration by Kiran Puri

Animating your keyboard (part 1)

New WindowInsets APIs for checking the keyboard (IME) visibility and size

New in Android 11 is the ability for apps to create seamless transitions between the on screen keyboard being opened and closed, and it’s all powered by lots of improvements to the WindowInsets APIs in Android 11.

Here you are two examples of it in action on Android 11. It has been integrated into the Google Search app, as well as the Messages app:

Two examples of keyboard animations in Android 11: Google Search app (left), Messages (right)

So let’s take a look at how you can add this sort of experience to your apps. There are three steps:

1. First, we need to go edge-to-edge.
2. The second step is for apps to start reacting to inset animations.
3. And the third step is by apps taking control of and driving inset animations, if it makes sense for your app.

Each of these steps follow on from each other, so we’ll cover each in separate blog posts. In this first post, we’ll cover going edge-to-edge, and the related API changes in Android 11.

Going edge-to-edge

Last year we introduced the concept of going edge to edge, as a way for apps to make the most of the new gestural navigation in Android 10:

Gesture Navigation: Going edge-to-edge (I)

As a quick re-cap, going edge to edge results in your app drawing behind the system bars, like you can see on the left.

To quote myself from last year:

By going edge-to-edge, apps will instead be laid out behind the system bars. This is to allow your app content to shine through to create a more immersive experience for your users.

So what has going edge to edge got to do with the keyboard?

Well going edge to edge is actually more than just drawing behind the status and navigation bars. It’s apps taking responsibility for handling those pieces of system UI which might overlap with the app.

The two obvious examples being the status bar and navigation bar, which we mentioned earlier. Then we have the on-screen-keyboard, or IME as it is sometimes referred to; it’s just another piece of system UI to be aware of.

How do apps go edge to edge?

If we flash back to our guidance from last year, going edge to edge is made up of 3 tasks:

1. Change system bar colors
2. Request to be laid out fullscreen
3. Handle visual conflicts

We’re going to skip the first task, because nothing has changed there since last year. The guidance for steps 2 & 3 has been updated with some changes in Android 11. Let’s take a look.

#2: Request to be laid out fullscreen

For the second step, apps needed to use the systemUiVisibility API with a bunch of flags, to request to be laid out fullscreen:

If you were using this API and have updated your compile SDK version to 30, you’ll have seen that all of these APIs are now deprecated.

They’ve been replaced with a single function on Window called setDecorFitsSystemWindows():

Instead of the many flags, you now pass in a boolean: false if apps want to handle any system window fitting (and thus go fullscreen).

We also have a Jetpack version of the function available in WindowCompat, which was released recently in androidx.core v1.5.0-alpha02.

So that’s the 2nd step updated.

#3: Handling visual conflicts

Now let’s look at the third step: avoiding overlaps with the system UI, which can be summarised as using the window insets to know where to move content to, to avoid conflicts with the system UI. On Android, insets are represented by the WindowInsets class, and WindowInsetsCompat in AndroidX

If we take a look at WindowInsets before the updates from API 30, the most common inset type to use is the system window insets. These cover the status and navigation bars, and also the keyboard when it is open.

To use WindowInsets, you would typically add an OnApplyWindowInsetsListener to a view, and handle any insets which are passed to it:

Here we’re fetching the system window insets, and then updating the view’s padding to match, which is a very common use case.

There are a number of other inset types available, including the recently added gesture insets from Android 10:

Similar to the systemUiVisibility API, much of the WindowInsets APIs have been deprecated, in favor of new functions to query the insets for different types:

• getInsets(type: Int) which will return the visible insets for the given types.
• getInsetsIgnoringVisibility(type: Int) which returns the insets, regardless of whether they’re visible or not.
• isVisible(type: Int) which returns true if the given type is visible.

We just mentioned ‘types’ a lot there. These are defined in the WindowInsets.Type class as functions, each returning an integer flag. You can combine multiple types, using a bitwise OR to query for combined types, which we’ll see in a minute.

All of these APIs have been backported to WindowInsetsCompat in AndroidX Core, so you can safely use them back to API 14 (see the release notes for more information).

So if we go back to our example from before, to update it to the new APIs, they become:

The IME type ⌨️

Now the keen eyed 👀 among may have been looking at this list of types, and been looking at one type in particular: the IME type.

Well we can finally answer this StackOverflow question, from over 10 years ago (fashionably late), about how to check the visibility of the keyboard. 🎉

How to check visibility of software keyboard in Android?

To get the current keyboard visibility, we can fetch the root window insets, and then call the isVisible() function, passing in the IME type.

Similarly if we want to find out the height, we can do that too:

If we need to listen to changes to the keyboard, we can use the normal OnApplyWindowInsetsListener, and use the same functions:

Hiding/showing the keyboard

Since we’re on a roll of answering StackOverflow questions, how about this one from 11 years ago, of how to close the keyboard.

How do you close/hide the Android soft keyboard?

Here we are going to introduce another new API in Android 11, called WindowInsetsController.

Apps can get access to a controller from any view, and then show or hide the keyboard by calling either show() or hide(), passing in the IME type:

But hiding and showing the keyboard isn’t all that the controller can do…

WindowInsetsController

Earlier we said that some of the View.SYSTEM_UI_* flags have been deprecated in Android 11, replaced with a new API. Well there were a number of other View.SYSTEM_UI flags available, related to changing the system UI appearance or visibility, including:

• View.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION
• View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN
• View.SYSTEM_UI_FLAG_LAYOUT_STABLE
• View.SYSTEM_UI_FLAG_LOW_PROFILE
• View.SYSTEM_UI_FLAG_FULLSCREEN
• View.SYSTEM_UI_FLAG_HIDE_NAVIGATION
• View.SYSTEM_UI_FLAG_IMMERSIVE_STICKY
• View.SYSTEM_UI_FLAG_IMMERSIVE
• View.SYSTEM_UI_FLAG_VISIBLE
• View.SYSTEM_UI_FLAG_LIGHT_STATUS_BAR
• View.SYSTEM_UI_FLAG_LIGHT_NAVIGATION_BAR

Similar to the others, these have also been deprecated too in API 30, replaced with APIs in WindowInsetsController.

Instead of going through the migration for all of these flags, we’ll cover a few common scenarios and see how to update them:

Immersive modes

Here you can see a drawing app, which hides the System UI to maximise the space available for drawing:

Markers app, demonstrating hiding the system UI

To implement that using WindowInsetsController we use the hide() and show() functions like before, but this time we pass in the system bars type:

The app also uses immersive mode, allowing the user to swipe the system bars back in once hidden. To implement this using WindowInsetsController we change the hide and show behaviour to BEHAVIOR_SHOW_BARS_BY_SWIPE:

Similarly, if you were using sticky immersive mode, this is implemented using the BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE instead:

Status bar content color

The next scenario is around the status bar content color. Here you see two apps:

Two apps, on the left an using a dark status bar background, and on the right using a light background

On the left the app has a dark status bar background, with light content like the time and icons. But if we instead want a light status bar background with dark content, like the right, we can use WindowInsetsController too.

To do that, we can use the setSystemBarsAppearance() function, passing in the APPEARANCE_LIGHT_STATUS_BARS value:

If you instead want to set a dark status bar, by passing in 0 instead to clear the value.

Note: you could implement this in your theme instead, by setting the android:windowLightStatusBar attribute. This might be preferable if you know the value won’t change.

Similarly, the APPEARANCE_LIGHT_NAVIGATION_BARS flag is available which provides the same functionality for the navigation bars.

WindowInsetsController in AndroidX?

Unfortunately a Jetpack version of this API does not exist yet, but we are working on it. Stay tuned.

Going edge-to-edge: ✔️

So that’s the first step done. In the next blog post we’ll investigate the second step: apps reacting to inset animations.

Animating your keyboard: Reacting to inset animations