Interactive by Nature

jQuery Mobile Custom Icons


It would be really nice if there was an easy way to create custom icons for jQuery Mobile. An ideal scenario, for me, would be to replace one of the un-needed icons in the provided icon set with my custom icon. Then, reference that icon by renaming the selector in the CSS. But, when I open the PNG, all the icons become jagged and pixelated. I’m not a Photoshop expert, so I could be doing something wrong. When opening icon-18-white.png in Photoshop, the files default color mode is Indexed Color. In order to edit this file, I need to change it. When I change the color mode, that’s when the icons degrade.


I created a new PNG with the two custom icons I need. Same height canvas as icon-18-white.png, but a different width to accommodate the custom icons. Save this file as a PNG with alpha transparency.

In the markup, you need to specify a unique identifier to the data-icon attribute. For example: data-icon=”email”. The button plugin in the jQuery Mobile framework will do the rest by applying this unique identifier to your button class. For example: ui-icon-email.

Here’s the markup:

<a href="tel:5555555555" data-role="button" data-icon="phone-touch" data-iconpos="right">555-555-5555</a>
<a href="" data-role="button" data-icon="email" data-iconpos="right"></a>

The CSS looks like this:

/* custom icons */
.ui-icon-email {
	background-image: url(/images/icons-18-white-custom.png);
	background-repeat: no-repeat;
.ui-icon-phone-touch {
	background-position: 0 50%;
.ui-icon-email {
	background-position: -36px 50%;

Because the jQuery Mobile framework prepends ui-icon- to the unique data-icon value, you must prepend ui-icon- to your CSS selector, like this: .ui-icon-email.


jQuery Mobile Custom Icons Result


  1. I tried this out -it DID work, there were a few things that were a strange though. For starters, I made only one icon to the same size as the icon-18-white.png I used your css but and POW -it worked, AFTER I also had to make changes to ui-icon and ui-icon-alt and switch THOSE to: background-image: url(../images/custom_icons.png; as well. Of course doing this disables any other icons in the original icon-18-white.png graphic. there was also one funny thing

    here is the final css I used
    /*.ui-icon-email*/ {
    /*background-image: url(../images/custom_icons.png);*/
    background-repeat: no-repeat;

    .ui-icon-task {
    background-position: 0px 50%;

    /*.ui-icon-email {
    background-position: -36px 50%;

    I did not use the other “email” icon so it’s commented out here. What did happen though is that IF I commment out
    /*background-image: url(../images/custom_icons.png);*/ -it still works! why is that?

    Evan on April, 22nd, 2011 at 8:16 am
  2. One other thing I noticed,

    Should the
    icons-36-white.png also be modified? as later in the css:

    you have:

    /* HD/”retina” sprite which appears to be intended for diplaying icons on certain devices -any ideas?

    Evan on April, 22nd, 2011 at 8:26 am
  3. Evan, the retina display icons do have to be modified as well. As for commenting out the background image; I bet it’s cached in the browser. It should not be working without an image source.

    admin on April, 22nd, 2011 at 8:51 am
  4. Hello,
    nice help 🙂

    Please, can you share your Icons for Mail and Phone? And share css Code for Retina-support?

    greets Roman

    Roman on April, 22nd, 2011 at 12:31 pm
  5. I wrote an article about Retina Display here.


    admin on April, 25th, 2011 at 10:37 am
  6. Thank you very much for this worked great for me 😉

    samuel on May, 25th, 2011 at 5:23 am
  7. Have you tested it on Android? I’m using Photoshop CS3, and when I save it out it doesn’t show on Android devices. :$

    Jane on August, 25th, 2011 at 4:32 pm
  8. Jane, yes I have tested on Android, iPhone and Blackberry OS6 +. Can you provide the markup and CSS you are working with?

    admin on August, 25th, 2011 at 7:15 pm
  9. Photoshop doesn’t support semi transparency on .png’s with indexed color. You can open them in fireworks. If you wanted, you could open in fireworks > save as 24bit png and then edit in photoshop.

    ken on December, 23rd, 2011 at 11:58 am
  10. Awesome Ken! Thanx for the tip.

    admin on December, 23rd, 2011 at 3:20 pm
  11. Thanks, It works great…

    Mahsa on May, 8th, 2012 at 7:30 am
  12. Got Better solution though not specialized for jquery Mobile just include this link in your aspx page:

    script src=”” type=”text/javascript”

    OR alternately download the file from

    Hrishikesh on May, 13th, 2012 at 4:19 am
  13. I have to respectfully disagree Hrishikesh. Your solution seems a bit excessive for a couple of custom icons. Especially if it’s for a mobile website where performance is very important. Downloading another framework/plugin will only increase the wait time for the end user.

    admin on May, 13th, 2012 at 10:54 am
  14. Great article, it actually explains what the docs hint at. Here is the same example with sprites…

    Clay Graham on June, 2nd, 2012 at 5:24 pm
  15. I tried this, and working fine, thanks a lot…

    Sanjay Kumar on September, 6th, 2012 at 10:47 pm
  16. […] jQuery Mobile Custom Icons […]

    jQuery Mobile Custom Icons | HERRENBART – Programming-Blog on January, 25th, 2013 at 3:46 pm

Leave a Comment