Text box ‘hint’ values with jQuery

On creating a rather large form recently, I was in the need to have some kind of hint to the user about what format the content should take on several input boxes. I could have done this with a description under the form element, but a more accepted way to do this, it seems, is to have a ‘hint’ in the element itself. You know the kind of thing I mean; a value, usually quite a light grey colour, that is present until you click in to the form element and then is disappears. I also wanted to do this as a jQuery plug-in because, well, why not? 🙂

There are some things to bare in mind with this kind of functionality. Obviously, you only want it to apply to text boxes and textareas – anything else is a waste of time… Even password fields are pointless to have a hint in them because it’ll only be a series of stars anyway!

The next thing to bare in mind is that you don’t want to reset the value if the user has typed anything in. And sometimes you may even want to accept the user typing exactly what the hint is, you you can’t just assume that if the value == the hint then it’s OK to clear.

And with those things in mind, here’s the plug-in:

/**
 * Form text box hints.
 * 
 * This plug-in will allow you to set a 'hint' on a text box or
 * textarea.  The hint will only display when there is no value
 * that the user has typed in, or that is default in the form.
 * 
 * You can define the hint value, either as an option passed to
 * the plug-in or by altering the default values.  You can also
 * set the hint class name in the same way.
 * 
 * Examples of use:
 * 
 *     $('form *').textboxhint();
 * 
 *     $('.date').textboxhint({
 *         hint: 'YYYY-MM-DD'
 *     });
 * 
 *     $.fn.textboxhint.defaults.hint = 'Enter some text';
 *     $('textarea').textboxhint({ classname: 'blurred' });
 *
 * @copyright Copyright (c) 2009, 
 *            Andrew Collington, andy@amnuts.com
 * @license New BSD License
 */
(function($) {
    $.fn.textboxhint = function(userOptions) {
        var options = $.extend({}, $.fn.textboxhint.defaults, userOptions);
        return $(this).filter(':text,textarea').each(function(){
            if ($(this).val() == '') {
                $(this).focus(function(){
                    if ($(this).attr('typedValue') == '') {
                        $(this).removeClass(options.classname).val('');
                    }
                }).blur(function(){
                    $(this).attr('typedValue', $(this).val());
                    if ($(this).val() == '') {
                        $(this).addClass(options.classname).val(options.hint);
                    }
                }).blur();
            }
        });
    };
    
    $.fn.textboxhint.defaults = {
        hint: 'Please enter a value',
        classname: 'hint'
    };
})(jQuery);

Some examples of use (as shown in the plug-in header comment, but I figure it can’t hurt to show it again!)

$('form *').textboxhint();

$('.date').textboxhint({
    hint: 'YYYY-MM-DD'
});

$.fn.textboxhint.defaults.hint = 'Enter some text';
$('textarea').textboxhint({ classname: 'blurred' });