A simple guide to 9-patch for Android UI

While I was working on my first Android app, I found 9-patch (aka 9.png) to be confusing and poorly documented. After a little while, I finally picked up on how it works and decided to throw together something to help others figure it out.

Basically, 9-patch uses png transparency to do an advanced form of 9-slice or scale9. The guides are straight, 1-pixel black lines drawn on the edge of your image that define the scaling and fill of your image. By naming your image file name.9.png, Android will recognize the 9.png format and use the black guides to scale and fill your bitmaps.

Here’s a basic guide map:

As you can see, you have guides on each side of your image. The TOP and LEFT guides are for scaling your image (i.e. 9-slice), while the RIGHT and BOTTOM guides define the fill area.

The black guide lines are cut-off/removed from your image – they won’t show in the app.  Guides must only be one pixel wide, so if you want a 48×48 button, your png will actually be 50×50. Anything thicker than one pixel will remain part of your image. (My examples have 4-pixel wide guides for better visibility. They should really be only 1-pixel).

Your guides must be solid black (#000000). Even a slight difference in color (#000001) or alpha will cause it to fail and stretch normally. This failure won’t be obvious either*, it fails silently! Yes. Really. Now you know.

Also you should keep in mind that remaining area of the one-pixel outline must be completely transparent. This includes the four corners of the image – those should always be clear. This can be a bigger problem than you realize. For example, if you scale an image in Photoshop it will add anti-aliased pixels which may include almost-invisible pixels which will also cause it to fail*. If you must scale in Photoshop, use the Nearest Neighbor setting in the Resample Image pulldown menu (at the bottom of the Image Size pop-up menu) to keep sharp edges on your guides.

*(updated 1/2012) This is actually a “fix” in the latest dev kit. Previously it would manifest itself as all of your other images and resources suddenly breaking, not the actually broken 9-patch image.

 

The TOP and LEFT guides are used to define the scalable portion of your image – LEFT for scaling height, TOP for scaling width. Using a button image as an example, this means the button can stretch horizontally and vertically within the black portion and everything else, such as the corners, will remain the same size. The allows you to have buttons that can scale to any size and maintain a uniform look.

It’s important to note that 9-patch images don’t scale down – they only scale up. So it’s best to start as small as possible.

Also, you can leave out portions in the middle of the scale line. So for example, if you have a button with a sharp glossy edge across the middle, you can leave out a few pixels in the middle of the LEFT guide. The center horizontal axis of your image won’t scale, just the parts above and below it, so your sharp gloss won’t get anti-aliased or fuzzy.

Fill area guides are optional and provide a way define the area for stuff like your text label. Fill determines how much room there is within your image to place text, or an icon, or other things. 9-patch isn’t just for buttons, it works for background images as well.

The above button & label example is exaggerated simply to explain the idea of fill – the label isn’t completely accurate. To be honest, I haven’t experienced how Android does multi-line labels since a button label is usually a single row of text.

Finally, here’s a good demonstration of how scale and fill guides can vary, such as a LinearLayout with a background image & fully rounded sides:

With this example, the LEFT guide isn’t used but we’re still required to have a guide. The background image don’t scale vertically; it just scales horizontally (based on the TOP guide). Looking at the fill guides, the RIGHT and BOTTOM guides extend beyond where they meet the image’s curved edges. This allows me to place my round buttons close to the edges of the background for a tight, fitted look.

So that’s it. 9-patch is super easy, once you get it. It’s not a perfect way to do scaling, but the fill-area and multi-line scale-guides does offer more flexibility than traditional 9-slice and scale9. Give it a try and you’ll figure it out quickly.

For more useful tips, follow me on Twitter.

Comments (77)

  1. awesome article!!!
    i hav written a code to click an image and set it on an imageview.
    nw how do i stretch this image?? i.e. dynamically…

  2. Pingback: Building Blocks: What Developers Wish Designers Knew | Ramblings from an Android Designer

  3. Pingback: Emil's Design - Strive For Perfection. » Blog Archive » Guide: 9-Patch Tools and Explanation:

  4. Thanks. I appreciate this explanation. Others (we will leave them nameless but they are well known) don’t do as good job explaining 9-patch as you have done here.

  5. So the stretching that happens in the scaling areas, how is that handled? Is there smoothing or other upsampling methods applied? Looks like you trust a gradient in those areas, but it might be good to cover that, if it is known.

    • For the most part it’s smooth. If you’re trying something very subtle, with little difference in a short area you may see banding. I’m used to seeing banding so I’ll often try gradients over and over until I get something smooth.

  6. Pingback: Android >> Crear un splash screen en Android | Escritor de códigos.

  7. Pingback: scaling a bitmap without losing quality - Delphi Solutions - Developers Q & A

  8. Pingback: Особенности разработки под Android на Titanium | infoblog

  9. Pingback: Tips for exporting assets for iOS & Android design – UNITiD. – UNITiD

  10. Pingback: Dear designer.. | Fokke Zandbergen

  11. Pingback: Vivien J. Lim » Android Design Guidelines

  12. Pingback: Android Design Guidelines | Chasing Lights

  13. Pingback: Supporting Multiple Screens Android : Android Community - For Application Development

  14. Pingback: Calculating a stretchable image with resizableImageWithCapInsets | BlogoSfera

  15. Pingback: Setting border color of some part of View : Android Community - For Application Development

  16. Pingback: Allow auto scaling in Android Drawables for various densities? : Android Community - For Application Development

  17. Pingback: Apply nine patch to irregular shaped images in android : Android Community - For Application Development

  18. First of all thank you for nice tutorial. My lot of confusions get clear but still I am stuck in one thing. I am going to create a 9 path image for my button. But, I could not understand what should be its size for xhdpi, hdpi, ldpi and mdpi.
    In tutorial you said image size should by 48×48 and after creating 1 pixel black line line its size become 50×50.

    Questions:
    1. Please tell me what should be original image size for xhdpi, hdpi, ldpi and mdpi?
    2. Do I first create an image for xhdpi, hdpi, ldpi and mdpi and then separately create 9 path image?

    • 1. mdpi is the same as dp in size, so 48dp is 48 pixels on an mdpi device.

      hdpi == 1.5x mdpi
      xhdpi == 2x mdpi
      xxhdpi == 3x mdpi

      So if you have a 48×48 image, it will need to be 72×72 for hdpi and 96×96 for xhdpi. Adding a 9-scale border to each will make the files 50×50, 74×74, and 98×98.

      2. Yeah, it’s best that way because Photoshop tends to add hard to see anti-aliasing which can break 9-scale markings. You’ll usually need to redraw by hand new guidelines, as well as run an eraser around the edge of the graphic, just to be sure it’s clean.

  19. Pingback: pandroid » PD021 – Ingress

  20. Good writeup!
    Along with the multiple stretch regions, would be worthwhile to point out:
    - trying to shrink the size of a 9patch (e.g. by specify height in xml that’s smaller than the image’s height) will typically result in nasty visual artefacts.
    - some tools available for creating/editing.

  21. Pingback: How to remove the border of edittextfield in android : Android Community - For Application Development

  22. Pingback: Creating 9 Patch Images - Android Asset Studio | Blundell

  23. Pingback: 9 Patch Graphic | rhapsodixx

  24. Pingback: Android界面制作中最重要最强大的武器: 9-patch | Freewind.me

  25. Pingback: Quora

  26. Pingback: ‘Droid Layouts and UI Design » Tarn Aeluin

  27. Pingback: 10 tips to create perfect visual assets for your app – UNITiD | Interaction Design & Usability

  28. Pingback: Anonymous

  29. Pingback: Android开发笔记——圆角和边框们 – 闲趣's Blog

  30. Pingback: [REF] Dev Tools for Windows - Android Forums

    • How to use 9 patch image in a android? Where 9 patch tools in Eclipse?
      When i use 9 patch image it gave error No resource found?
      Plz give proper guideliness.

      In adv Thanks.

  31. Great article! :)

    However, there’s something I don’t understand: if I don’t use the LEFT guide (because I don’t want the image to be stretched vertically), I get this error message: “No marked region found along edge. – Found along left edge”.

    I think I must be missing something, but I can’t figure out what’s wrong.

    Thanks a lot!

    • Nice catch. I checked out my actual working assets and turns out I did use a left guide, even though I’m not scaling vertically.

      I’ve updated the graphic and post. Thanks for catching that =)

  32. Very helpful! Thanks so much for your article.

    Question: Normally Android recommends that you provide multiple versions of each image to account for different screen sizes/resolutions. Is that still required when you use a 9 Patch image? If you only need a single 9 Patch image for all resolutions, which baseline resolution do you pick?

    Thanks so much.

    • There’s about a 30% size difference between mdpi & hdpi so I always do 2x screen images; I do mdpi & hdpi and ignore ldpi. By my understanding, mdpi is the standard baseline for dp scaling: layouts match mdpi and scale from there to hdpi.

  33. One other thing that I don’t think is documented on the official page, is that you can actually have more than one “stretchable” region on each side. There are a few .9.png files in the SDK that use this.

    So imagine you have an icon in the middle of a button that you don’t want to stretch, but you do want the space either side of the icon to stretch… Your top black line would be in 2 parts, either side of the icon.

Leave a Comment

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code class="" title="" data-url=""> <del datetime=""> <em> <i> <q cite=""> <strike> <strong> <pre class="" title="" data-url=""> <span class="" title="" data-url="">