Change the app icon

1. Before you begin

An app icon is an important way to distinguish your app. It also appears in a number of places including the Home screen, All Apps screen, and the Settings app.

You may also hear the app icon referred to as a launcher icon. Launcher refers to the experience when you hit the Home button on an Android device to view and organize your apps, add widgets and shortcuts, and more.

If you've tried different Android devices, you may have noticed that the Launcher experience can look different depending on the device manufacturer. Sometimes device manufacturers will create a custom Launcher experience that's signature to their brand. As part of that, different manufacturers may show app icons in a different shape than the circular icon shape shown above.

They could display all the app icons in a square shape, rounded square, or squircle (between a square and circle) for example.

Regardless of the shape the device manufacturers choose, the goal is for all the app icons on a single device to have a uniform shape for a more consistent user experience.

That's why the Android platform introduced support for adaptive icons (as of API level 26). By implementing an adaptive icon for your app, your app will be able to accommodate a large range of devices by displaying a high-quality app icon appropriately.

This codelab will provide you with image source files for a Tip Calculator launcher icon to practice with. You will use a tool in Android Studio called Image Asset Studio to generate all versions of the launcher icons needed. Afterwards, you can take what you learned and apply it to changing the app icon for other apps!

Prerequisites

• Able to navigate the files of a basic Android project, including the resource files
• Able to install an Android app from Android Studio on the emulator or a physical device

What you'll learn

• How to change the launcher icon of an app
• How to use Image Asset Studio in Android Studio to generate launcher icon assets
• What is an adaptive icon and why it's made up of two layers

What you'll build

• An Android app that has a new launcher icon

What you need

• A computer with the latest stable version of Android Studio installed
• Internet connection to download the image resource files

2. Set up your project

If you're taking this codelab as part of the Android Basics in Kotlin course, you can directly use the tip calculator from the previous codelab that you're already working on.

If you're taking this codelab on its own (outside of the course), you can set up a new project in Android Studio using the Empty Activity template. That way you don't modify or overwrite launcher icon files in an existing app until you are more comfortable with these steps.

3. Launcher Icons

The goal is for your launcher icon to look fantastic (crisp and clear) regardless of the device model or screen density. Specifically, screen pixel density refers to how many pixels per inch (or dpi, dots per inch) are on the screen. For a medium-density device (mdpi), there are 160 dots per inch on the screen while an extra-extra-extra-high-density device (xxxhdpi) has 640 dots per inch on the screen.

To account for devices across a range of screen densities, you'll need to provide different versions of your app icon.

Explore launcher icon files

1. To see what this looks like, open up your project in Android Studio. If your app was started from a template, then you should have default launcher icons that are already provided by Android Studio.
2. In the Project window, switch to the Project view. This will show you the files in your project according to the file structure of how those files are saved on your computer.

3. Navigate to the resources directory (app > src > main > res) and expand out some of the mipmap folders. These mipmap folders are where you should put the launcher icon assets for your Android app.

mdpi, hdpi, xhdpi, etc.. are density qualifiers that you can append onto the name of a resource directory (like mipmap) to indicate that these are resources for devices of a certain screen density. Here's a list of density qualifiers on Android:

• mdpi - resources for medium-density screens (~160 dpi)
• hdpi - resources for high-density screens (~240 dpi)
• xhdpi - resources for extra-high-density screens (~320 dpi)
• xxhdpi - resources for extra-extra-high-density screens (~480dpi)
• xxxhdpi - resources for extra-extra-extra-high-density screens (~640dpi)
• nodpi - resources that are not meant to be scaled, regardless of the screen's pixel density
• anydpi - resources that scale to any density

Note: You may wonder why launcher icon assets are located in mipmap directories separate from other app assets located in drawable directories. This is because some launchers may display your app icon at a larger size than what's provided by the device's default density bucket. For example, on a hdpi device, a certain device launcher may want to use the xhdpi version of the app icon instead.

4. If you click on the image files, you'll see a preview. The ic_launcher.png files contain the square version of the icon, while the ic_launcher_round.png files contain the circular version of the icon. Both are provided in each resource directory.

For example, this is what res > mipmap-xxxhdpi > ic_launcher_round.png looks like. Also notice the size of the asset is in the top right. This image is 192px x 192px in size.

On the other hand, this is what res > mipmap-mdpi > ic_launcher_round.png looks like. It's only 48px x 48px in size.

As you can see, these bitmap image files are composed of a fixed grid of pixels. They were created for a certain screen resolution. Hence the quality can degrade as you resize them.

If you scale down a bitmap image, it will probably look okay because you are getting rid of pixel information. If you scale up a bitmap image significantly, it may appear blurry because Android will need to guess at and fill in the missing pixel information.

Note: To avoid a blurry app icon, be sure to provide different bitmap images of an app icon for each density bucket (mdpi, hdpi, xhdpi, etc...) Note that device screen densities won't be precisely 160dpi, 240dpi, 320dpi, etc... Based on the current screen density, Android will select the resource at the closest larger density bucket and then scale down.

Now that you have some background context on launcher icons, you'll learn about adaptive icons next.

4. Adaptive Icons

Foreground and Background Layers

As of the Android 8.0 release (API level 26), there is support for adaptive launcher icons, which allows for more flexibility and interesting visual effects when it comes to app icons. For developers, that means that your app icon is made up of two layers: a foreground and a background layer.

In the above example, the white Android icon is in the foreground layer, while the blue and white grid is in the background layer. The foreground layer will be stacked on top of the background layer. Then a mask (circular mask in this case) will be applied on top to produce a circular shaped app icon.

Explore adaptive icon files

Look at the default adaptive icon files provided by the project template in Android Studio.

1. In the Project window of Android Studio, look for and expand out the res > mipmap-anydpi-v26 resource directory.

Note: Adaptive icons were added in API level 26 of the platform, so the adaptive icons should be declared in a mipmap resource directory that has the -v26 resource qualifier on it. That means the resources in this directory will only be applied on devices that are running API 26 (Android 8.0) or higher. The resource files in this directory are ignored on devices running older versions of the platform.

2. Open up one of the XML files, for example ic_launcher.xml. You should see this:

<?xml version="1.0" encoding="utf-8"?>
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
    <background android:drawable="@drawable/ic_launcher_background" />
    <foreground android:drawable="@drawable/ic_launcher_foreground" />
</adaptive-icon>

3. Notice how the <adaptive-icon> element is used to declare the <background> and <foreground> layers of the app icon by providing resource drawables for each.
4. Go back to the Project view and look for where the drawables are declared: drawable > ic_launcher_background.xml and drawable-v24 > ic_launcher_foreground.xml.
5. Switch to Design view to see a preview of each (background on left, foreground on right).

6. These are both vector drawable files. They don't have a fixed size in pixels. If you switch to Code view, you can see the XML declaration for the vector drawable using the <vector> element.

While a vector drawable and a bitmap image both describe a graphic, there are important differences.

A bitmap image doesn't understand much about the image that it holds, except for the color information at each pixel. On the other hand, a vector graphic knows how to draw the shapes that define an image. These instructions are composed of a set of points, lines, and curves along with color information. The advantage is that a vector graphic can be scaled for any canvas size for any screen density, without losing quality.

A vector drawable is Android's implementation of vector graphics, intended to be flexible enough on mobile devices. You can define them in XML with these possible elements. Instead of providing versions of a bitmap asset for all density buckets, you only need to define the image once. Thus, reducing the size of your app and making it easier to maintain.

Note: there are tradeoffs to using a vector drawable versus a bitmap image. For example, icons can be ideal as vector drawables because they are made up of simple shapes, while a photograph would be harder to describe as a series of shapes. It would be more efficient to use a bitmap asset in that case.

Now it's time to move onto actually changing the app icon!

5. Download new assets

Next, download these 2 new assets that will enable you to create an adaptive icon for a Tip Calculator app. You don't need to worry about understanding every detail of the vector drawable files. Their contents can get auto-generated for you from design tools.

1. Download ic_launcher_background.xml, the vector drawable for the background layer. If your browser shows the file instead of downloading it, select File > Save Page As... to save it to your computer.
2. Download ic_launcher_foreground.xml, the vector drawable for the foreground layer.

Note that there are certain requirements on these foreground and background layer assets, such as both must be 108dp x 108dp in size. More details on the requirements here or you can see the design guidance on Android icons on the Material site.

Because the edges of your icon could get clipped depending on the shape of the mask from the device manufacturer, it's important to put the key information of your icon in a " safe zone" which is a circle of diameter 66 dp in the center of the layer. The content outside of that safe zone should not be essential (e.g. background color) where it's okay if it gets clipped.

6. Change the app icon

Go back to Android Studio to use the new assets.

1. First delete the old drawable resources that have the Android icon and green grid background. In the Project view, right click on the file and choose Delete.

Delete:

drawable/ic_launcher_background.xml
drawable-v24/ic_launcher_foreground.xml

You can uncheck the box Safe delete (with usage search) and click OK.

2. Create a new Image Asset. You could right click on the res directory and choose New > Image Asset. Or you can click on the Resource Manager tab, click the + icon, and select Image Asset.

3. Android Studio's Image Asset Studio tool opens.
4. Leave the default settings:

Icon Type: Launcher Icons (Adaptive and Legacy)

Name: ic_launcher

5. With the Foreground Layer tab already selected, go down to the Source Asset subsection. On the Path field, click the folder icon.
6. A prompt pops up to browse your computer and select a file. Find the location of the new ic_launcher_foreground.xml file you just downloaded on your computer. It may be in the downloads folder of your computer. Once you've found it, click Open.
7. The Path is now updated with the location of the new foreground vector drawable. Leave Layer Name as ic_launcher_foreground and Asset Type as Image.

8. Next switch to the Background Layer tab of the interface. Leave defaults as-is. Click the folder icon of the Path.
9. Find the location of the ic_launcher_background.xml file you just downloaded. Click Open.

10. The preview should be updating as you select the new resource files. This is what it should look like with the new foreground and background layers.

By representing your app icon in two layers, device manufacturers (called original equipment manufacturers or OEMs for short) can create different shapes depending on the Android device, as shown in the preview above. The OEM provides a mask that gets applied to all app icons on the device.

This mask gets applied on top of the foreground and background layers of your app icon. Example of a circular mask and square mask below.

When a circular mask is applied to both layers of your app icon, the result is a circular icon with a blue grid background and an Android in it (left image above). Alternatively, you could apply a square mask to produce the app icon in the above right.

Having two layers also allows for interesting visual effects because the two layers can move independently or be scaled. For some fun examples of how the visual effects can look, check out this blogpost under Design Considerations. Because you can't tell in advance what device your user will have or what mask the OEM will apply onto your icon, you need to set up your adaptive icon so important information doesn't get cut off.

11. Make sure the main contents of the foreground layer (the service bell icon in this case) are contained within the safe zone and not clipped by the different mask shapes. If important content is clipped or appearing too small, then you can use the Resize slider bar under the Scaling section of each layer. In this case, no resizing is needed, so you can leave it at 100%.

12. Click Next.
13. This step is to Confirm Icon Path. You can click the individual files to see the preview. There's also a warning at the bottom that some existing files will be overwritten (shown in red). That is okay because those old files were for the previous app icon.

14. The defaults are fine, so click Finish.
15. Verify all the generated assets look correct in the mipmap folders. Examples:

Great work! Now you'll do one more change.

Move vector drawable files into -v26 directory

Depending on the min SDK of your app, you may notice that the background asset is located in the drawable-v24 folder, while the foreground asset is in the drawable folder. The reason is because the background asset contains a gradient, which was available starting in the Android 7.0 release (also known as API version 24, hence the -v24 resource qualifier). The foreground asset doesn't contain a gradient, so that can go in the base drawable folder.

Instead of having the foreground and background assets in two separate drawable folders, move both vector drawable files into a -v26 resource directory. Since these assets are only used for adaptive icons, these two drawables are only needed on API 26 and above. This folder structure will make it easier to find and manage your adaptive icon files.

drawable-anydpi-v26
   ic_launcher_background.xml
   ic_launcher_foreground.xml
mipmap-anydpi-v26
   ic_launcher.xml
   ic_launcher_round.xml

1. First create the drawable-anydpi-v26 directory. Right click on the res folder. Select New > Android Resource Directory.
2. New Resource Directory dialog will appear. Select these options:

Directory name: drawable-anydpi-v26

Resource type: drawable (Select from dropdown)

Source set: main (leave default value as-is)

Click OK. In the Project view, verify the new resource directory res > drawable-anydpi-v26 has been created.

3. Left click on the ic_launcher_foreground.xml file and drag it from the drawable folder into the drawable-anydpi-v26 folder. Recall that putting a resource in an "any dpi" directory indicates that it's a resource that can scale to any density.
4. Left click on the ic_launcher_background.xml and drag it from the drawable-v24 folder into the drawable-anydpi-v26 folder.
5. Delete the drawable-v24 folder if it's empty now. Right click on the folder and then select Delete.
6. Click through all the drawable and mipmap files in your project. Make sure the preview of these icons look correct.

Test your app

1. Test that your new app icon appears. Run the app on your device (emulator or physical device).
2. Hit the home button on your device.
3. Swipe up to show the All Apps list.
4. Look for the app you just updated. You should see the new app icon displayed.

Note: Depending on your device model, you may see a launcher icon of a different shape. But nevertheless, it should show your foreground layer on top of your background layer with some type of mask applied to it.

Nice job! The new app icon looks great.

Adaptive and legacy launcher icons

Now that your adaptive icon works well, you may be wondering why you can't get rid of all the app icon bitmap images. You still need those files so that your app icon appears high-quality on older versions of Android, which is referred to as backwards compatibility.

On devices running Android 8.0 or higher (API version 26 and above):

Adaptive icons can be used (combination of foreground vector drawable, background vector drawable, with an OEM mask applied on top of it). These are the relevant files in your project:

res/drawable-anydpi-v26/ic_launcher_background.xml
res/drawable-anydpi-v26/ic_launcher_foreground.xml
res/mipmap-anydpi-v26/ic_launcher.xml
res/mipmap-anydpi-v26/ic_launcher_round.xml

On devices running anything below Android 8.0 (but above the minimum required API level of our app):

Legacy launcher icons will be used (the bitmap images in the mipmap folders of different density buckets). These are the relevant files in your project:

res/mipmap-mdpi/ic_launcher.png
res/mipmap-mdpi/ic_launcher_round.png
res/mipmap-hdpi/ic_launcher.png
res/mipmap-hdpi/ic_launcher_round.png
res/mipmap-xhdpi/ic_launcher.png
res/mipmap-xhdpi/ic_launcher_round.png
res/mipmap-xxdpi/ic_launcher.png
res/mipmap-xxdpi/ic_launcher_round.png
res/mipmap-xxxdpi/ic_launcher.png
res/mipmap-xxxdpi/ic_launcher_round.png

Essentially, Android will fall back to the bitmap images on older devices without adaptive icon support.

Congratulations, you have completed all the steps for changing an app icon!

7. Solution code

The solution code for this codelab is below.

res/mipmap-anydpi-v26/ic_launcher.xml

<?xml version="1.0" encoding="utf-8"?>
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
    <background android:drawable="@drawable/ic_launcher_background" />
    <foreground android:drawable="@drawable/ic_launcher_foreground" />
</adaptive-icon>

res/mipmap-anydpi-v26/ic_launcher_round.xml

<?xml version="1.0" encoding="utf-8"?>
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
    <background android:drawable="@drawable/ic_launcher_background" />
    <foreground android:drawable="@drawable/ic_launcher_foreground" />
</adaptive-icon>

res/drawable-anydpi-v26/ic_launcher_background.xml

<vector xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:aapt="http://schemas.android.com/aapt"
    android:width="108dp"
    android:height="108dp"
    android:viewportWidth="108"
    android:viewportHeight="108">
  <path
      android:pathData="M0,0h108v108h-108z">
    <aapt:attr name="android:fillColor">
      <gradient
          android:startY="-1.0078"
          android:startX="54"
          android:endY="106.9922"
          android:endX="54"
          android:type="linear">
        <item android:offset="0" android:color="#FF12C26D"/>
        <item android:offset="1" android:color="#FF0F9453"/>
      </gradient>
    </aapt:attr>
  </path>
</vector>

res/drawable-anydpi-v26/ic_launcher_foreground.xml

<vector xmlns:android="http://schemas.android.com/apk/res/android"
    android:width="108dp"
    android:height="108dp"
    android:viewportWidth="108"
    android:viewportHeight="108">
  <path
      android:pathData="M38.19,65.92L69.32,65.92a1.2,1.2 0,0 0,1.2 -1.2,0.89 0.89,0 0,0 0,-0.23 17,17 0,0 0,-33.25 0,1.18 1.18,0 0,0 0.9,1.42ZM74.53,69.05a0.85,0.85 0,0 0,-0.78 -0.84L34,68.21a0.85,0.85 0,0 0,-0.77 0.84v2.82a0.84,0.84 0,0 0,0.77 0.86L73.78,72.73a0.85,0.85 0,0 0,0.77 -0.86L74.55,70.65C74.55,70.24 74.56,69.58 74.53,69.05ZM52.08,49h3.59a1.86,1.86 0,0 0,0 -3.72L52.08,45.28a1.86,1.86 0,0 0,0 3.72ZM53.87,39.81a1.19,1.19 0,0 0,1.19 -1.19L55.06,32.87a1.19,1.19 0,0 0,-2.38 0v5.71a1.19,1.19 0,0 0,1.19 1.19h0ZM61.69,41l4.62,-3.35a1.19,1.19 0,1 0,-1.4 -1.93L60.29,39A1.2,1.2 0,0 0,60 40.67a1.18,1.18 0,0 0,1.66 0.26ZM41.69,37.65L46.31,41a1.2,1.2 0,0 0,1.35 -2L43,35.66a1.19,1.19 0,0 0,-1.66 0.26,1.2 1.2,0 0,0 0.3,1.67Z"
      android:fillColor="#FFFFFF"/>
</vector>

Bitmap images should also have been auto generated by Android Studio in these locations:

res/mipmap-mdpi/ic_launcher.png
res/mipmap-mdpi/ic_launcher_round.png
res/mipmap-hdpi/ic_launcher.png
res/mipmap-hdpi/ic_launcher_round.png
res/mipmap-xhdpi/ic_launcher.png
res/mipmap-xhdpi/ic_launcher_round.png
res/mipmap-xxdpi/ic_launcher.png
res/mipmap-xxdpi/ic_launcher_round.png
res/mipmap-xxxdpi/ic_launcher.png
res/mipmap-xxxdpi/ic_launcher_round.png

8. Summary

• Place app icon files in the mipmap resource directories.
• Provide different versions of an app icon bitmap image in each density bucket (mdpi, hdpi, xhdpi, xxhdpi, xxxhdpi) for backwards compatibility with older versions of Android.
• Add resource qualifiers onto resource directories to specify resources that should be used on devices with a certain configuration (e.g. v26).
• Vector drawables are Android's implementation of vector graphics. They are defined in XML as a set of points, lines, and curves along with associated color information. Vector drawables can be scaled for any density without loss of quality.
• Adaptive icons were introduced to the Android platform in API 26. They are made up of a foreground and background layer that follow specific requirements, so that your app icon looks high-quality on a range of devices with different OEM masks.
• Use Image Asset Studio in Android Studio to create legacy and adaptive icons for your app.

9. Learn more

• Design guidelines on Android icons
• Adaptive Icons
• Understanding Android Adaptive Icons
• Designing Adaptive Icons
• Implementing Adaptive Icons
• Adaptive Icon Playground app
• Create Adaptive and Legacy Launcher icons
• Supporting different pixel densities
• Put app icons in mipmap directories
• Vector Drawables Overview
• VectorDrawable class