Advanced Customization of the jQuery Mobile Buttons

There are many ways to skin a cat

By default, jQuery Mobile offers a series of themes that you can use in your project. Chances are that your project has been designed with unique buttons and elements that defer from the standard  jQuery Mobile Themes. In this article I will show a couple of techniques that you can use to do advanced customization of a jQuery Mobile Button in a way  that your code can be reused across multiple projects. Here is the list of points that I will touch upon:

  1. The structure of  the jQuery Mobile Button
  2. Simple customization
  3. Adding a custom theme
  4. Reset the button theme
  5. Advanced element targeting
  6. Adding elements using CSS
  7. Adding elements using Javascript
  8. Icon-only buttons
  9. Targeting buttons by context
  10. Conclusion

The structure of  the jQuery Mobile Button

The first thing that we need to keep in mind is, what are the HTML elements that we are going to modify. In the case of a jQuery Mobile Button, the HTML code that you define is different from the HTML code that is rendered when the page is done loading:


The modified HTML structure takes multiple CSS rules in order to render the final button. When you look at the name of some of the CSS classes you may inquire which part of the button is rendered on each element. For instance, the positioning of the button is delegated to the “a” tag. The class ui-btn-left will force the button to float to the left side if the button is located inside the page header (this class is only assigned to the first instance of a button).

The different visual states of the buttons can be access from the “a” tag. In this example the button uses the theme a. jQuery Mobile automatically add the CSS class ui-btn-up-a which will allow us to customize the  look-and-feel of the button in its default state (when the mouse is positioned outside of the button). When the mouse hovers the button, or when we click on it, this class is replaced with ui-btn-hover-a and ui-btn-down-a respectively. Similarly, when we choose a different theme, the letter “a” in the name of the classes is replaced with the name of the theme (i.e. ui-btn-up-custom).

The body of the button is represented by the span.ui-btn-inner. This element is responsible for the background color of the button. You can modify the way the label of the button by targeting the span.ui-btn-text element. As you can predict, the icon of the button is rendered inside the span.ui-icon.

The final look-and-feel is the result of a combination of the background colors, borders, and shadows. This is a complex setup, but the jQuery Mobile Framework provides easy ways to create variations of the button.


Simple customization

Although this article is about advanced customization, I will touch on some of the basic techniques.

The Themeroller

You are probably familiar with the jQuery Mobile Themeroller. This is an online tool that allows you to customize global and theme-specific parameter to control the fonts, color, borders and shadows of the standard jQuery Mobile elements.

jQuery Mobile Themeroller


If you have not seen the Themeroller tool, you should visit the jQuery Mobile site and learn about it. It is a fun tool to play with. After you are done creating you theme you can download a archive file (.zip) containing the file that you will need to reference in you project (Visit jQuery Mobile Themeroller).


Using Custom Icons

In some cases you may want to simply change the icon of a button. The way to do that is by adding or replacing the icon attribute in your button HTML code. Inside the button, the span tag that controls the icon will inherit a CSS class that will contain the name of your icon. This will allow you to right the appropriate CSS code to add a new icon. One thing to keep in mind is that the default size of the icon is 18px x 18px. It is also placed inside a circular shape with a shadow effects applied to it. The following code show how to add a logo icon (24×24 pixles) and remove the shadow effect:

Creating custom icon for a jQuery Mobile Button


Controlling the position of the icon

This is probably on of the easiest thing that you can change. By  simple adding the attribute data-iconpos=”right” you can float the icon to the right. This attribute accept the following values: left, right, top, button, and notext which remove the button label, leaving just the icon.


Selection a default theme

You can have more control over the different parts and states of the button when you add a custom theme. The jQuery Mobile Framework provides 5 default swatches. They are identified with the letters “a” thru “e“. You may choose other letters to create your own theme or simply assign a name to you theme.

jQuery Mobile Default Swatches

jQuery Mobile default swatches


Adding a custom theme

When you assign a custom theme to a button, jQuery Mobile assigns several CSS classes to different part of the button that you can use to add your custom code. Here is an example of a theme that I will ios:

jQuery Mobile Button - iOS Theme


As you can see the CSS rules have to be defined for the three different states of the button. In this example I chose to remove the shadow and change the button radius using some CSS rules.


Reset the button theme

So far, the examples that I provided do not require much code. As you create more themes, for more elements, for more project, you will see the amount of code growing exponentially. You might end up copying-and-pasting code from one project to another or even between pages.

To make sure that you reuse code from one theme to another, it makes sense to keep the CSS reset rules in a common file. In this way you will only write theme-specific rules on a theme by theme basis. Writing the reset rules separate will give you a blank canvas that you can customize with less effort. Here is a suggested reset code:


jQuery Mobile Reset Buttons


Notice that in this example I am only targeting elements that are buttons and have the reset theme assigned. The CSS reset rules that are valid for a button element might not be valid for a navigation element. Instead of writing rules around the the reset class (ui-btn-up-reset, ui-btn-hover-reset, and ui-btn-down-reset) it makes sense to target the theme and the specific element type. On top of the reset theme we can add other CSS classes to modify the appearance of the button without having to repeat the reset rules.

The idea behind this type of manipulation is not to complicate things. It is to assure that we can preserve the HTML structure of the pages and create any type of button around the HTML elements that are generated by the jQuery Mobile Framework.


I want to learn more advanced techniques

  • (required)
  • Should be Empty:
In a nutshell: we DO NOT share your information with anyone. Learn more about our Privacy Policy.


Advanced element targeting

Now that we have an idea about the some of the options that we have to customize a button, let’s combine what we discuss so far. The following example will show how to create a theme family that you can extend while preserving the reset rules in a separate file:

The complete HTML code (app-ios-theme.html)


The reset code (app-reset.css)


The iOS-like theme code (app-ios.css)

jQuery Mobile Buttons – iOS Theme


Adding elements using CSS

Imagine that you need to make a one time change to a button. This is an interesting scenario. The following example show how to add a “new” badge to a button using CSS pseudo selectors to modify the HTML structure:


Inline cose to accommodate the badge

jQuery Mobile Button + Badge


Adding elements using Javascript

There are scenarios where you might need to create a more complex structure inside the button. In the article How to Make an iPhone Back Button in jQuery Mobile we show how to add a DIV and  a SPAN element inside an jQuery Mobile button (<div><span></span></div>).

jQuery Mobile - iOS-like back button


In order to create the point for the button we added a SPAN tag that takes a linear gradient from the upper left corner to the lower right corner. The SPAN tag is rotated 45 degrees and the DIV tag is scaled to make the shape of a diamond. The new elements are added from a callback function that is trigger when the document loads:

Adding elements using a callback function


If you choose to use Javascript to modify the structure of a button, be aware that your mobile application might load other pages and your code might have to be executed again to make sure that the newly loaded page inherit the changes.


Icon-only buttons

If you just want to get rid of the button background and text all together, you apply the reset theme and focus on the icon. The example below uses a standard navigation bar but removes the background, borders, and text label from the button.

jQuery Mobile Buttons - Icon-only


Targeting buttons by context

Finally, remember that the look-and-feel of a button will change depending on where the button is located. For instance, buttons located inside a controlgroup will be connected so you will have to write additional CSS rules to acknowledge different context. In the case of the a crontrolgroup the main element inherits the CSS class ui-controlgroup. You can use this class name as your starting point in your CSS selector:


Change the text color only if the button is inside a controlgroup

jQuery Mobile Button - Controlgroup



Throughout this article we discussed how to customize standard jQuery Mobile buttons in ways that will give you absolute control over the look-and-feel. In some cases you might feel that it is easier to simply turn your custom button into an image and stick it inside an “a” tag. You might be right. It is easier, but not scalable. From the visual viewpoint, today’s web is more dynamic. The screen size and resolution of the devices are constantly evolving. The application layout is becoming more responsive. To accommodate for all this changes you need to pick a strategy that is efficient, flexible, and more important, pain-free. Addressing elements customization using CSS while preserving the original HTML structure might not be the easiest way, but it is certainly more scalable path.

Click HERE to download the source code and basic examples showing how to customize jQuery Mobile Buttons.

Advanced jQuery Custom Buttons

Download Custom Buttons Example



What do you think of this post?

8 Responses to “Advanced Customization of the jQuery Mobile Buttons”

  1. Manish Kumar August 21, 2012 at 9:05 am #

    Great article. It helps me a lot in understanding the theme concept.

  2. Dusan December 23, 2012 at 4:08 pm #

    Nice job, thanks for sharing!

  3. Christopher February 6, 2013 at 12:56 pm #

    Great article, very thorough! Really helped me understand what’s going on behind the scenes with buttons in jQuery Mobile.

  4. Steve February 19, 2013 at 12:45 am #

    Very detailed, excellent breakdown. Thanks dude

  5. Elias March 21, 2013 at 2:31 pm #

    Very good!! the details, the explanation!! thanks for sharing!

  6. Bill March 27, 2013 at 1:48 am #

    Excellent! I’m fairly new to jQuery Mobile and this was a great look at customization approaches by someone that obviously has a lot of experience in this area. Thanks for sharing!

  7. Stacey June 13, 2013 at 3:01 am #

    Thank you! Thank you! THANK YOU! :) I have been stuck for over an hour trying to figure out how to display just my icon. The reset code helped me so much!

Leave a Reply