iGrowl

iGrowl is a lightweight jQuery plugin that generates growl-like notifications with an emphasis on icons. Alerts are fully responsive and CSS animations are used to provide optimal performance. The plugin also includes 4 optional icon packs.

Demo

Installation

iGrowl has 3 dependencies:

jQuery
animate.css
at least one of the 4 icon packs included in the .zip - each includes the respective css and font files
- Vicons by Victor Erixon
- Feather by Cole Bemis
- Steadysets by Tommy Sähl
- Linecons by Sergey Shmidt

All icon packs have been compiled using the Icomoon app.

To get started, include the following in your project:

<-- dependencies: jQuery + animate.css --> 
<link rel="stylesheet" href="stylesheets/animate.min.css">
<script src="javascript/jquery.js">


<-- iGrowl CSS + JS --> 
<link rel="stylesheet" href="stylesheets/igrowl.min.css">
<script src="javascript/igrowl.min.js">


<-- at least one of the following icon stylesheets: --> 
<link rel="stylesheet" href="stylesheets/vicons.css">
<link rel="stylesheet" href="stylesheets/feather.css">
<link rel="stylesheet" href="stylesheets/steadysets.css">
<link rel="stylesheet" href="stylesheets/linecons.css">

Also, include the respective font files (eg: igrowl-feather.eot, igrowl-feather.svg, igrowl-feather.ttc, etc).

Note: you may need to change the icon CSS paths to the font files depending on how your project is organized.

To install via Bower: $ bower install igrowl.

Getting started

Usage

To generate an iGrowl alert, simply call it by:

$.iGrowl({
 message: "Hello world!",
 // other properties...
})

Properties

The full list of iGrowl properties:

Property	Default	Type	Description
`type`	`'info'`	`string`	Type of alert, available options are: `info, success, notice, error, simple`For a more saturated/deeper color style, add the `-sat` suffix, eg: `info-sat, success-sat, notice-sat, error-sat`
`title`	`null`	`string`	Alert title (optional)
`message`	`null`	`string`	Alert message (optional)
`icon`	`null`	`string`	Icon class (optional), in the form of `iconPack-iconName`
`link`	`null`	`string`	Encapsulates the entire alert in a link
`target`	`self`	`string`	Anchor target of alert (if link property above is specified), options are: `self, blank`
`image[src]`	`null`	`string`	Image source to include in alert - overrides icon.
`image[class]`	`null`	`string`	Classes to add to `div` containing the image (optional).
`delay`	`2500`	`number`	Delay before alert auto-dismisses (optional). Set to `0` for persistence.
`small`	`false`	`boolean`	Size of alert - either regular or small
`spacing`	`30`	`number`	Spacing between alerts
`placement[x]`	`'right'`	`string`	Horizontal placement, accepts: `left, center, right`
`placement[y]`	`'top'`	`string`	Vertical placement, accepts: `top, bottom`
`offset[x]`	`20`	`number`	Horizontal offset from edge of window
`offset[y]`	`20`	`number`	Vertical offset from edge of window
`animation`	`true`	`boolean`	Enable or disable animation
`animShow`	`'bounceIn'`	`string`	Alert animation on enter
`animHide`	`'bounceOut'`	`string`	Alert animation on exit
`onShow`	`null`	`function`	Function to run once enter animation begins, will not run if animation is set to `false`
`onShown`	`null`	`function`	Function to run once enter animation completes
`onHide`	`null`	`function`	Function to run once exit animation begins, will not run if animation is set to `false`
`onHidden`	`null`	`function`	Function to run once exit animation completes

Note: alerts do not necessarily need both a message and a title.

You can include links in alerts through 2 ways:

using the link property which causes the entire alert to be a link,
adding links in the message or title as html, eg:

$.iGrowl({
 title : 'This item right <a href="http://www.link.com">here</a> is a link',
 // other properties
})

For a detailed example, see here.

Changing default settings

To change the default settings:

$.iGrowl.prototype.defaults.property_name = desired_default


// examples
$.iGrowl.prototype.defaults.icon = 'feather-cog'
$.iGrowl.prototype.defaults.placement.y = 'bottom'

Public Methods

You can manually dismiss individual alerts by:

var growl = $.iGrowl({ title: 'Welcome to the jungle' })

growl.dismiss()

To dismiss all alerts, call $.iGrowl.prototype.dismissAll( placement ):

// dismisses all alerts
$.iGrowl.prototype.dismissAll('all')

// dismisses all alerts at right top
$.iGrowl.prototype.dismissAll('right top')

// dismisses all alerts at center bottom
$.iGrowl.prototype.dismissAll('center bottom')

Examples

Simple growl alert with icon, title and message.

$.iGrowl({
 title: 'Having issues?',
 message: 'Chat with a technician for support',
 icon: 'vicons-support'
})

Displaying an error in the bottom-center position.

$.iGrowl({
 type: 'error',
 title: 'Uh oh - something went wrong!',
 icon: 'linecons-fire',
 placement : {
  x: 	'center',
  y: 	'bottom'
 }
})

Small alert with no animation.

$.iGrowl({
 title: 'Welcome to the internet!',
 message: 'We hope you enjoy your stay.',
 small: true,
 animation: false,
 delay: 3000
})

Alert containing an image.

/* custom styling */
.example-image img {
 border-radius: 50%;
 border: 3px solid #FACC54;
}

$.iGrowl({
 type: 'notice',
 delay: 5000,
 title: 'New friend request',
 message: 'Greg Jackson has sent you a friend invite!',
 image: {
  src: './images/user.jpg',
  class: 'example-image'
 }
})

Alert containing a link with a _blank anchor target, and an alert containing a link in the message property.

// entire alert is a link
$.iGrowl({
 icon : 'feather-image',
 message : 'Looking for a great image gallery?',
 link : 'http://imgur.com/',
 target : 'blank',
 delay : 6000
})

// link is contained in part of the message
$.iGrowl({
 icon : 'feather-image',
 // message uses: <a href="http://imgur.com/" target="_blank">Click here</a>'
 message : 'Looking for a great image gallery? Click here',
 delay : 6000
})

Persistent alert 100px from the top and 80px spacing between alerts.

$.iGrowl({
 type: 'success',
 icon: 'vicons-envelope',
 message: 'You have mail!',
 delay: 0,
 spacing: 80,
 offset : {
  y: 	100
 }
})

fadeInLeftBig and fadeOutDown animations, and onHidden callback.

$.iGrowl({
 type: 'notice',
 message: 'The item has been added to your cart',
 icon: 'vicons-cart',
 placement : {
  x: 	'center'
 },
 animShow: 'fadeInLeftBig',
 animHide: 'fadeOutDown',
 onHidden: function(){
  alert('alert is now hidden!')
 }
})

Custom styles & icon sets

Creating your own custom styles is easy.

.igrowl-customeName {
 background: customColor;
 border-color: customColor;
 
 .igrowl-message { color: customColor; }
 .igrowl-title { color: customColor; }
 .igrowl-icon { color: customColor; }
}

and then use your style by:

$.iGrowl({
 type : 'customName',
 // other properties
})

You can use your own icon sets. If they're images, just pass the source path to the image[src] property. If you're trying to incorporate an icon font, try to follow the iGrowl font structure by using one of the iGrowl font icon css (ie: linecons.css, vicons.css, etc) for reference.

By default, when you pass an icon name to iGrowl such as linecons-pen it adds the i-linecons-pen class to the div containing the icon. To set up your icon set:

[class^="i-iconSetName-"], [class*=" i-iconSetName-"]  {
 font-family: 'iconSetName';
 
 /* other styling (see icon css for reference)  */
}

Then assign each icon a unicode/ligature:

.i-iconSetName-iconName:before {
 content: "icon-code";
}

To use via iGrowl:

$.iGrowl({
 icon : 'iconSetName-iconName',
 // other properties
})

Contributing

If you find any bugs, have feature requests, or would like to contribute - either send me a pull request or open a ticket and I'll do my best to follow up on it.

Developed and maintained by Catalin Covic under the MIT license.