jQuery UI: Icon Radio Buttons

If you have a group of radio buttons, you can use the buttonset widget to make them look like a jQuery UI widget. That is, you call the buttonset() plugin on a container element, usually a div, and the widget groups the radio button labels together, and applies styles from the theme framework. For example, here's what a radio buttonset widget looks like by default.

Custom Accordion Header Icons

The jQuery UI accordion widget has an icons option that let's the developer change the defaults. The defaults use the ui-icon-triangle-1-e icon for the collapsed state, and the ui-icon-triangle-1-s icon for the expanded state. These are classes taken from the theme framework, and so the fundamental limitation is that you have to use an icon that's already there. Either that, or extend the available icons available to your theme. The latter option is painful if all you want to do is use an accordion header icon specific to the content found in that section.

A Clear Text Input Widget

A standard requirement of most user interfaces is that the input elements have a clear text button. This is generally rendered as a small "x" on the right side of the input. When the user clicks this "x" icon, any text entered in the input is removed. It makes sense to add such a capability into a widget since you'll be applying it to input elements throughout the application. Let's see how this is done using jQuery UI.

Button Icon Option Shortcut

The button widget, allows you to set the primary icon, the secondary icon, or both. The primary icon shows up the left of the button text, and of the text isn't displayed, it's just the primary icon that's displayed. The secondary icon shows up to the right of the button text. In general, the primary icon is the common path. However, the button options API is expecting an object every time we want to change just the primary button. Let's see how we can optimize for the common case and provide a simplified icon API.

Menu Icon Fix For jQuery UI

With a few additional elements in the markup, it's easy to add icons to jQuery UI menu widgets. We simply place spans to the left of the menu item text. We also have to add the relevant icon classes from the theme framework. That's the easy part. However, since we're manually changing the way the widget is rendered, there's no guarantee that it'll look how it's supposed to. And in fact, there is a minor issue with the icon placement — they're slightly too high.

Icons in jQuery UI Autocomplete Items

Adding custom display data to jQuery UI autocomplete items is easy. All we need is a basic CSS class with some custom properties, and the willingness to override the default implementation of the _renderItem() method. It's one thing to include some meta data about each item in the autocomplete drop-down. It's much more interesting, I think, when you display icons beside each item. Ready?

jQuery UI: Check If Icon Exists

I like the way jQuery UI icons work. You just need a class, generally named after the thing the icon represents, and that class points to a specific location of an image. This approach supports extensibility. You add new icons to the theme images, and add new icon classes that point to them. While this is very useful, I couldn't help but wonder — how to we make sure that the icon actually exists before using it? For example, the jQuery widgets themselves aren't aware of which theme is in use, but if you're adding non-standard icons to one theme, but not another, this capability could be handy.

jQuery UI: Icon Widget

The jQuery UI theme framework comes with a bunch of icons. Useful icons. I use them a lot, but not necessarily inside a widget, like an icon button for example. Icons are effective conveyors of information and state. I like user interfaces that user icons to represent things where it makes sense, and to have those icons change state when attention is needed. And adding text to those icons in the form of a tooltip, to further communicate to the user. All great things, all very awkward to implement. I'm constantly repeating myself when using stand-alone jQuery UI icons. So, I went all out. I took care the issue by creating a simple icon widget that took care of the boiler-plate for me.

jQuery UI Icon Buttons

The jQuery UI button widget is flexible in that it can have several different configurations.  They can display text only, icon only, or a combination of the two.  This setup works with either a button or an anchor as the underlying element.  So right out of the box, the button widget is flexible enough to use more than one HTML element type.

One thing the button can't do without modification is display as an icon — without the other theme attributes like the border and background styles.  So if you want a button that only displays as an icon, maybe for a help button placed beside a text input, you've no choice but to alter the button.  An alternative is to extend the theme — to directly modify the theme to not display the border or background styles for button widgets. 

Let's look at an example.  Suppose we want a help button beside a text input — to tell the user what the input is for should they want to know.  When clicked, this button might display the contextual help in a dialog or expand some otherwise closed HTML content.  To do so with a regular button, we might implement the following HTML...

<body>
    <div>
        <input type="text"/>
        <button id="regular_button" title="Help">Help</button>
    </div>
</body>

And here is the Javascript used to instantiate the button widget, passing it a primary icon argument...

$(document).ready(function(){
    $('#regular_button').button({text:false, icons:{primary:'ui-icon-help'}});
});

Here is what the resulting layout looks like...

Without much effort on out part, we've now got a help button accompanying our text input - ready to respond to click events and display contextual content.  However, we're more concerned with the look and feel of this context button.  Might it be that in this button in it's default form might be a little overkill?  Let's try making this help button a little less invasive. 

First, we'll build on our current HTML structure so we can compare the two button formats...

<body>
    <div>
        <input type="text"/>
        <button id="regular_button" title="Help">Help</button>
    </div>
    <div>
        <input type="text"/>
        <button id="icon_button" title="Help">Help</button>
    </div>        
</body>

Next, we're going to create a new button widget — one that builds on the default button implementation...

$.widget('ui.iconbutton', $.extend({}, $.ui.button.prototype, {
    _init: function() {
        $.ui.button.prototype._init.call(this);
        this.element.removeClass('ui-corner-all')
                    .addClass('ui-iconbutton')
                    .unbind('.button');
    }		
}));

$(document).ready(function(){
    $('#regular_button').button({text:false, icons:{primary:'ui-icon-help'}});
    $('#icon_button').iconbutton({text:false, icons:{primary:'ui-icon-help'}});
}); 

Finally, our new button implementation needs to be themed...

.ui-iconbutton {
    background: transparent;
    border: none;
}

The demo page now has two text inputs and two corresponding help buttons — the latter using our new button implementation that only shows the icon...

As you can see, iconbutton removes the border and background styles from the button — aside from that, we've got a regular button image.  With this widget customization, we're only modifying the appearance.

Did we have to create a custom widget just to remove the border and background styles from a button?  Could we not have just applied the appropriate help icon class to a span element and achieve the same result with less work?  Absolutely, we could have.  But in the end, creating a custom widget implementation has several benefits that aren't discernible at first.

The key advantage to this approach is that the iconbutton and button widgets are interchangeable.  Since the iconbutton is simply extending the button widget, it accepts the same parameters.  This is why I'm illustrating both buttons on the same page — the HTML and Javascript are identical except for the widget name.  What this means is that if you don't want the icon button any more, it can simply be replaced by a regular button.  Conversely, the icon button can replace regular buttons.