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.

Share :


  • GameDevelopment
    January 12, 2017 at 7:54 am  - Reply

    This is a great quick guide on what a nine patch is and how to create one.

  • Kibi
    July 7, 2015 at 8:51 am  - Reply

    Thanks so much – by far the simplest guide I have seen – helped me understand what wa wrong with my 9.png (black lines were thicker than one px)

  • Stephane
    May 27, 2015 at 7:55 am  - Reply

    These round images are beautiful. Any way to have some ready made ?

    The best guide on 9 patch I’ve seen. Helpful for a noob like me.

  • Harish Pathak
    February 10, 2015 at 5:40 am  - Reply

    I am trying to use 9-patch images in ios but maybe it’s not recognising these as 9 patch even i’ve named these images like abc.9.png
    If i am using these images ‘a black border’ is coming. that is 1 px guide line as u said in ur tutorial. how to remove it.
    or am I missing something, Please help!!!

    • radley
      February 14, 2015 at 10:53 am  - Reply

      I’ve never done 9-scale for iOS, so can’t offer advice. Maybe someone else will chime in.

    • K17
      May 2, 2015 at 1:38 am  - Reply

      9patch is a Google designed, Android-specific file format. It does not run natively on iOS (though there may be libraries out there to support them).

  • Mike
    January 30, 2015 at 3:45 pm  - Reply

    I’d like to echo everyone else’s sentiments: great guide!

    I think one part of the guide is slightly misleading. In that bottom example with the three circular images inside the button of a fixed height, it says “Left guide is not used so height remains the same”

    To me, that implies that if you put the 9patch in a layout taller than the button’s native height, and tell it to match_parent, it won’t grow at all (the “height remains the same”) and it will stay at its native height as though you had set it to wrap_content.

    “Nobody” asked about this on on June 4 and you replied:
    Android won’t recognize a 9-scale without something on the left side. That’s why I did a full bar, so it stretches naturally, which in this case is not at all.

    So I tried this out, and it does indeed stretch vertically (“naturally” just like images normally stretch) . How is that “not at all”? I assume you mean it won’t stretch if you tell it that the height should wrap_content. Is that the only way to make a button not stretch vertically? There’s nothing you can do inside of the 9patch so it’ll ensure it won’t stretch even if it’s in a layout that tries to stretch it?


    • radley
      February 14, 2015 at 10:45 am  - Reply

      Ah, good catch. Normally your ImageView container should limit the stretching. Otherwise, make your image’s canvas two pixels taller (but centered) and add two single-pixel scale marks on the left, each aligned with the new empty space. Make sure the new row is truly empty – you don’t want to stretch anti-aliased portions of your image.

  • the_new_mr
    January 18, 2015 at 11:53 am  - Reply

    Thanks man! I thought I had padding understood but couldn’t find anywhere on the net that confirmed apart from your excellent post. Thanks again!

  • Gordon Illan
    January 14, 2015 at 7:21 pm  - Reply

    Is there a way to fill the display with edge pixels without scaling the image in the center. For instance, if I have a 20×20 while circle in the center of a 100×100 red background, is it possible to stretch the red background only leaving the 20×20 circle intact? Thank you.

    • radley
      January 18, 2015 at 12:24 pm  - Reply

      Sure – add two stretch lines on either side of the circle, but not within the circle. The lines need to be the same length on each side so they stretch evenly on each side of the circle. Finally, if the outside area is a single color, you can just do a 1-pixel stretch line which will essentially stretch the color of the corresponding pixel.

  • Kouretinho
    September 8, 2014 at 4:12 am  - Reply

    Best guide on the internet about NinePatch images. Thanks for sharing man. Android documentation is still (3 yrs later) so insufficient, it’s not even funny…

  • Alex
    August 20, 2014 at 2:15 pm  - Reply

    This was hugely helpful. I do have one question–if I’d like to create a stretchable icon with a non-stretchable graphic in the center, could I assign two individual stretch points across the top and two down the left to create a stretchable padding inside the icon?

    • radley
      September 17, 2014 at 12:01 pm  - Reply

      Yes, exactly like that.

  • Erika
    August 8, 2014 at 9:14 am  - Reply

    Hi, im confuse the guides lines must be solid black or transparent ?… and when you save the image, you save in for example ths one is 48×48 but i save in 50×50?? please help!
    Thank you !

  • Nobody
    June 4, 2014 at 7:17 am  - Reply

    Thanks for the helpful input. But I am confused in your last scale & scale example. The text says “Left scale is not used, so height remains the same”, but the image beside shows a full left scale (from left top to left bottom). Shouldn’t it be empty instead?

    • radley
      June 27, 2014 at 6:55 pm  - Reply

      Android won’t recognize a 9-scale without something on the left side. That’s why I did a full bar, so it stretches naturally, which in this case is not at all.

  • Aditya
    May 10, 2014 at 7:35 am  - Reply

    Good post! I was not able am now able to to understand the 9-patch but done it bro! Hats off to you

  • ch
    February 27, 2014 at 6:19 am  - Reply

    Got it. Thanks.

  • Johnson Maung
    February 26, 2014 at 2:02 am  - Reply

    a Few … But its a complete awesome Post….

  • Rohit
    February 25, 2014 at 10:22 pm  - Reply

    well done bro…i really appreciate those who are making life easy for developers..and u r one of them..thanks a a lot.. :)

  • Ritu
    February 7, 2014 at 8:29 am  - Reply

    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…

  • anoir
    January 19, 2014 at 8:24 am  - Reply

    thanks, very good explanation.

  • piero
    October 5, 2013 at 1:35 pm  - Reply

    Thank you, more easy to understand than official Google documentation

  • Andrew
    September 21, 2013 at 11:50 pm  - Reply

    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.

  • Tridib Ghosh
    September 16, 2013 at 1:36 am  - Reply

    I am a fresher in mobile app designing field.
    What is left scale & right scale?

  • Will Capellaro
    September 3, 2013 at 9:21 am  - Reply

    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.

    • radley
      September 16, 2013 at 10:56 am  - Reply

      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.

  • Joe
    June 5, 2013 at 1:16 pm  - Reply

    This is the first place I have seen an example like the rounded asset you shown. Quite a nice trick

  • S.Dhanalakshmi
    March 12, 2013 at 7:45 am  - Reply

    Very useful.Thank you.

  • Vincent
    February 26, 2013 at 10:37 am  - Reply

    Wanted to take a minute to tell you great job with your article! Exactly what I was looking for, clear explanation & examples!

  • Marco
    February 22, 2013 at 2:57 am  - Reply

    My compliments. In the ufficial docs it’s not clearly stated the different usage for the right/bottom guides and the top/left ones…

  • Zuby
    February 19, 2013 at 10:21 pm  - Reply

    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.

    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?

    • radley
      February 20, 2013 at 1:42 am  - Reply

      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.

  • Zerho
    February 18, 2013 at 4:14 pm  - Reply

    The Stackoverflow link about multi line example is broken :(

    • radley
      February 18, 2013 at 5:05 pm  - Reply

      Oh well. I removed the reference to it since I couldn’t find another example. Thanks for letting me know!

  • Ifad Ardin
    February 15, 2013 at 11:40 pm  - Reply

    Your read my mind and answer my need. Thank you!

  • Linden
    January 17, 2013 at 8:02 am  - Reply

    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.

  • Zubair
    January 2, 2013 at 8:27 am  - Reply

    thanx for sharing .
    A good introduction to 9-patch images

  • Lakeside Techies
    December 25, 2012 at 3:18 am  - Reply

    The info is very helpful to gain more information on 9-patch for Android. It would be better if you could provide a simple example PSD… just a suggestion.

  • Mohamed Rafiq
    December 17, 2012 at 11:17 pm  - Reply

    Thanks a lot!!

  • arun
    December 1, 2012 at 3:13 am  - Reply

    I want to tile certain regions in a png.not the whole png. 9 patched areas only needs to be tiled. is it possible ?

    • radley
      December 1, 2012 at 3:48 am  - Reply

      Tile or stretch? 9 patch is meant for stretching, not tiling. They’re simply opposing forms of math…

  • Julio
    November 4, 2012 at 2:11 am  - Reply

    Thanks a million. I worked many times with nine patch but now I understand perfectly how they work.

  • raptor41
    October 27, 2012 at 4:18 pm  - Reply

    That was very helpful and easy to understand, thanks!

  • Nakes
    October 27, 2012 at 12:28 pm  - Reply

    Simple and clarifying explanation.

  • chandu
    September 25, 2012 at 11:14 pm  - Reply

    Thanks a lot!!!

  • cocoa
    July 25, 2012 at 10:36 am  - Reply

    Android need to hire you for explaining a lot of their stuff. The dev site is really…lacking

  • Ed
    July 24, 2012 at 2:24 am  - Reply

    Thank you, well explained!

  • Emilios
    July 18, 2012 at 7:12 am  - Reply

    Thanks!! your guide is amazing!

  • unplugged
    February 29, 2012 at 9:45 pm  - Reply

    ho God, thanks for the write up!!
    its well explained

  • JohnS
    February 1, 2012 at 6:42 am  - Reply

    Great write-up. Thank you.

  • Gubatron
    December 14, 2011 at 4:01 pm  - Reply

    THANK YOU! I finally understand.

  • Atli
    December 9, 2011 at 2:00 am  - Reply

    You rock! Finally I understood, the android documentation is terrible, thanks for putting this out.

    • wellwisher
      September 11, 2012 at 1:34 am  - Reply

      Great tutorial.. All my doubts got clarified.. expecting more on different topics..

  • Jason
    November 19, 2011 at 8:50 pm  - Reply

    This is a fantastic explanation of 9 patch. Thank you for taking the time to create it.

  • Lasse
    November 7, 2011 at 5:39 am  - Reply

    Awesome post! Easy to understand – thumbs up.

    • Charmme
      September 20, 2011 at 10:28 pm  - Reply

      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.

  • David
    June 8, 2011 at 3:11 am  - Reply

    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!

    • radley
      June 8, 2011 at 9:47 am  - Reply

      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 =)

  • Sara
    June 7, 2011 at 11:23 am  - Reply

    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.

    • radley
      June 7, 2011 at 11:58 am  - Reply

      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.

  • Radu
    May 24, 2011 at 8:45 am  - Reply

    Very useful ! Thank you !

  • Richard Leggett
    May 18, 2011 at 10:48 am  - Reply

    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 Reply