I’ve been hunting for a good jQuery Growl look-a-like plugin for some time, but I just can’t seem to find one that looks the exact same as the one for Mac OS, so like most web dabblers would do, I decided to roll my own.

For those who don’t know what Growl is, it’s basically a notification bubble/popup that appears in the top right of your desktop – examples can be found here. Think of it as calling the alert() function in JavaScript, only it’s not a modal, it’s subtle and it doesn’t look like dog shit.

Download It!

Demo It!

Ruby on Rails user? Download the Gritter plugin for Ruby on Rails

The example above is also included in the download

Note: If you’re wanting to know how to integrate Gritter with CakePHP as a flash message, read this article. It’s in Spanish, I know, but if you’re slightly familiar with CakePHP, the code is what really matters.

This article has also been written in Belarusian

Usage

First, make sure the folder structure is in place (images/js/css).

Now add this to the head of your document:

<link rel="stylesheet" type="text/css" href="css/gritter.css" />
<script type="text/javascript" src="http://www.google.com/jsapi"></script>
<script type="text/javascript">google.load('jquery', '1.5');</script>
<script type="text/javascript" src="js/jquery.gritter.js"></script>

Adding a simple notification

$.gritter.add({
	// (string | mandatory) the heading of the notification
	title: 'This is a notice!',
	// (string | mandatory) the text inside the notification
	text: 'This will fade out after a certain amount of time.'
});

Adding a more complex notification

$.gritter.add({
	// (string | mandatory) the heading of the notification
	title: 'This is a regular notice!',
	// (string | mandatory) the text inside the notification
	text: 'This will fade out after a certain amount of time.',
	// (string | optional) the image to display on the left
	image: 'http://a0.twimg.com/profile_images/59268975/jquery_avatar_bigger.png',
	// (bool | optional) if you want it to fade out on its own or just sit there
	sticky: false, 
	// (int | optional) the time you want it to be alive for before fading out (milliseconds)
	time: 8000,
	// (string | optional) the class name you want to apply directly to the notification for custom styling
	class_name: 'my-class',
        // (function | optional) function called before it opens
	before_open: function(){
		alert('I am a sticky called before it opens');
	},
	// (function | optional) function called after it opens
	after_open: function(e){
		alert("I am a sticky called after it opens: \nI am passed the jQuery object for the created Gritter element...\n" + e);
	},
	// (function | optional) function called before it closes
	before_close: function(e, manual_close){
                // the manual_close param determined if they closed it by clicking the "x"
		alert("I am a sticky called before it closes: I am passed the jQuery object for the Gritter element... \n" + e);
	},
	// (function | optional) function called after it closes
	after_close: function(){
		alert('I am a sticky called after it closes');
	}
});

If you wanted to use the “sticky: true” option but still be able to delete it later, you can create a variable that will hold a unique identifier.

var unique_id = $.gritter.add({
	// (string | mandatory) the heading of the notification
	title: 'This is a sticky notice!',
	// (string | mandatory) the text inside the notification
	text: 'This will not go away until the user has hit the (x) button because sticky has been set to true.',
	// (string | optional) the image to display on the left
	image: 'http://a0.twimg.com/profile_images/59268975/jquery_avatar_bigger.png',
	// (bool | optional) if you want it to fade out on its own or just sit there
	sticky: true
});

Now to delete that specific notification you can call:

$.gritter.remove(unique_id, { 
	fade: true, // optional
	speed: 'fast' // optional
});

To remove all Gritter notifications you can call:

$.gritter.removeAll();

As well as 

$.gritter.removeAll({
        before_close: function(e){
		alert("I am called before all notifications are closed.  I am passed the jQuery object containing all  of Gritter notifications.\n" + e);
	},
	after_close: function(){
		alert('I am called after everything has been closed.');
	}
});

If you want you can setup global defaults (optional)

Setting up global defaults is handy if you don’t want to specify a ‘time’ attribute for each $.gritter.add call.

$.extend($.gritter.options, { 
        position: 'bottom-left', // defaults to 'top-right' but can be 'bottom-left', 'bottom-right', 'top-left', 'top-right' (added in 1.7.1)
	fade_in_speed: 'medium', // how fast notifications fade in (string or int)
	fade_out_speed: 2000, // how fast the notices fade out
	time: 6000 // hang on the screen for...
});