jQuery Awesome Cursor plugin

A jQuery plugin for using FontAwesome icons as custom CSS cursors.

See https://jwarby.github.io/jquery-awesome-cursor/ for the full documentation and demos.

$('body').awesomeCursor('pencil');

Requires jQuery and FontAwesome.

Getting started

Installing the plugin

via bower: Easiest

bower install jquery-awesome-cursor

<link rel="stylesheet" href="bower_components/fontawesome/css/font-awesome.min.css" type="text/css">
<script src="bower_components/jquery/dist/jquery.min.js" type="text/javascript"></script>
<script src="bower_components/jquery-awesome-cursor/dist/jquery.awesome-cursor.min.js" type="text/javascript"></script>

via npm: Easier

npm install jquery-awesome-cursor

<link rel="stylesheet" href="node_modules/font-awesome/css/font-awesome.min.css" type="text/css">
<script src="node_modules/jquery/dist/jquery.min.js" type="text/javascript"></script>
<script src="node_modules/jquery-awesome-cursor/dist/jquery.awesome-cursor.min.js" type="text/javascript"></script>

manual installation

Download the production version or the development version.

In your web page:

<link rel="stylesheet" href="/path/to/font-awesome.min.css" type="text/css">
<script src="/path/to/jquery.js"></script>
<script src="path/to/jquery.awesome-cursor.min.js"></script>

Documentation

Setting a cursor

You can set a FontAwesome cursor on any element by calling awesomeCursor, and passing the name of the icon you want to use:

$('body').awesomeCursor('<icon name>');

See http://fontawesome.io/icons/ for a list of available icons.

Setting cursor options

Colour

Cursors can be any color you want, specified as a CSS color:

$('body').awesomeCursor('eyedropper', {
  color: '#ff0000'
})

$('body').awesomeCursor('eyedropper', {
  color: 'rgba(255, 255, 255, 0.75)'
})

$('body').awesomeCursor('eyedropper', {
  color: 'cyan'
});

$('body').awesomeCursor('eyedropper', {
  color: 'hsl(90, 100%, 50%)'
});

Size

Cursors can be any size (specified in pixels):

$('body').awesomeCursor('pencil', {
  size: 32
});

Only pixel values are supported, as CSS cursor hotspots can only be specified in pixels.

Hotspot

The hotspot for a cursor can be defined, with an array containing the hotspot's x and y offsets:

$('body').awesomeCursor('pencil', {
  hotspot: [0, 17]
});

Or, using a string descriptor:

$('body').awesomeCursor('pencil', {
  hotspot: 'bottom left'
});

String descriptors

The following values can be used in the hotspot string descriptor:

• 'center': positions the hotspot's x and y offset in the center of the cursor
• 'left' : positions the hotspot's x offset on the left of the cursor (equivalent to 0)
• 'right' : positions the hotspot's x offset on the far right of the cursor (equivalent to cursorSize - 1)
• 'top' : positions the hotspot's y offset at the top of the cursor (equivalent to 0)
• 'bottom': positions the hotspot's y offset at the bottom of the cursor (equivalent to cursorSize - 1)

The descriptors can be combined by space-separating them, e.g.:

• 'top left'
• 'center left'
• 'bottom right'
• 'top right'
• etc.

Flip

Cursors can be flipped horizontally, vertically, or in both directions, by setting the flip option:

// Horizontal flip
$('body').awesomeCursor('pencil', {
  flip: 'horizontal'
});

// Vertical flip
$('body').awesomeCursor('pencil', {
  flip: 'vertical'
});

// Horizontal and Vertical flip
$('body').awesomeCursor('pencil', {
  flip: 'both'
});

Rotate

A cursor can be rotated any number of degrees using the rotate option:

// 45 degrees clockwise
$('body').awesomeCursor('pencil', {
  rotate: 45
});

// 105 degrees anti-clockwise
$('body').awesomeCursor('pencil', {
  rotate: -105
});

// Horizontal and Vertical flip
$('body').awesomeCursor('pencil', {
  flip: 'both'
});

Examples

/* Set the body element's cursor to a green pencil, with the hotspot located at the bottom left of the cursor (where the
 * pencil tip is):
 */
$('body').awesomeCursor('pencil', {
  color: 'green',
  hotspot: 'bottom left'
});

// Set the cursor to be a big blue location arrow icon:
$('body').awesomeCursor('location-arrow', {
  color: '#0050FF',
  hotspot: 'top right',
  size: 48
});

// Set the cursor to be a horizontally flipped version of the location arrow
$('body').awesomeCursor('location-arrow', {
  color: '#0050FF',
  hotspot: 'top right',
  size: 48,
  flip: 'horizontal'
});

Browser Support

• Chrome
• FireFox

Bugs and Feature Requests

• https://github.com/jwarby/jquery-awesome-cursor/issues

Contributing

See CONTRIBUTING.md

Roadmap

• Allow cursors to be flipped (vertically and/or horizontally) and rotated by an abitrary number of degrees
• Optional outlines for cursors
• IE11 support (if possible)
• Data API (under consideration)
• Support for composite cursors made of up of multiple icons, a la FontAwesome stacked icons (under consideration)

Release History

• v0.0.4 - 29th Nov 2014 - Add rotate option for rotating cursor by a specified number of degrees. Flip transformation now applied after other transformations (e.g. rotate)
• v0.0.3 - 17th Nov 2014 - Fix an error in the README file
• v0.0.2 - 17th Nov 2014 - Add the flip option to allow cursors to be flipped horizontally, vertically, or in both directions
• v0.0.1 - 10th Nov 2014 - First version