jQuery Awesome Cursor

A jQuery plugin for using FontAwesome icons as custom CSS cursors. Works in Chrome and FireFox.

Try hovering over this!

Now also supports using an alternative icon font!


View on GitHub Fork me on GitHub!

Installation

In your terminal:

npm install jquery-awesome-cursor

In your web page:

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

If you plan on using jquery-awesome-cursor with a different icon font, you can skip the FontAwesome dependency:

npm install --no-optional jquery-awesome-cursor

In your terminal:

              bower install jquery-awesome-cursor
              

In your web page:

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

IMPORTANT: As of v0.3.0, FontAwesome is considered an optional dependency. Therefore, you must install it yourself!

              bower install font-awesome
              

The download links below are for the latest versions of the code, which may be unstable.

To view the latest stable release, and previous releases, please visit https://github.com/jwarby/jquery-awesome-cursor/releases .

Download just the script:

  jquery.awesome-cursor.min.js (production)   jquery.awesome-cursor.js (development)

Or download an archive of the latest code:

  .zip   .tar.gz

Then, in your web page:

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

You could also use RawGit's CDN:

<link rel="stylesheet" href="path/to/font-awesome.min.css">
<script src="path/to/jquery.min.js"></script>
<script src="https://cdn.rawgit.com/jwarby/jquery-awesome-cursor/master/dist/jquery.awesome-cursor.min.js"></script></pre>
              

Usage

To set a cursor on an element, just call $('<selector>').awesomeCursor('<icon name>');

For example, to use the pencil icon as the <body> element's cursor, do the following:


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

Cursors also support a number of options, which are detailed in the next section.

Options are set by passing an object as the second parameter to awesomeCursor():


$('body').awesomeCursor('pencil', {
  /* your options here */
});
      

Resetting the cursor

You can reset the cursor to it's previous icon using jQuery's css function:

$('body').css('cursor', '');

Options

The cursor attributes can be configured using the options listed below.

type: String

The first parameter to awesomeCursor is the icon name.


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

Try it now!

Pssst! Stuck for ideas? Try these: paint-brush paper-plane expand hand-o-up ban
type: String

The color of a cursor can be changed by setting the color option to any valid CSS color string:

  • 'red'
  • 'rgb(255, 0, 0)'
  • 'hsl(0, 100%, 50%)'
  • etc.

$('body').awesomeCursor('pencil', {
  color: 'red'
});

Try it now!

type: Number

The size of the cursor can be changed by setting the size option.

Note: cursor sizes can only be defined in pixels, as the cursor hotspot CSS syntax only supports pixels


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

Try it now!

type: String or Array

The hotspot location of the cursor can be defined using the hotspot option. This allows you to configure the point that the actual click will emanate from.

The hotspot can be configured in two different ways: using an array containing the [x, y] coordinates (in pixels) of the hotspot, or by using a descriptive string.

If you're using an array of coordinates, the values will be clamped between 0 and the size of the cursor minus 1. This is because the browser will default to 0, 0 for coordinates beyond the boundaries of the cursor.


Example: defining the hotspot using an array

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

Example: defining the hotspot using a descriptive string

The strings 'bottom', 'top', 'left', 'right' and 'center' are recognised. These values can be combined by space-separating them; some examples are shown below:

  • 'bottom left'
  • 'center'
  • 'center top'
  • 'center right'
  • 'top right'

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

Try it now!



Click below to test hotspot location:
type: String

The cursor can be flipped horizontally, vertically, or in both directions by setting the flip option.

flip can be one of:

  • horizontal
  • vertical
  • both

To disable flipping, set flip to any falsy value (false, null, '', etc.). All other values will result in an error being thrown.


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

Try it now!

type: Number

The cursor can be rotated any number of degrees using the rotate option.


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

Try it now!

type: String

An outline can be applied to a cursor by setting the outline option to any valid CSS color string.


$('body').awesomeCursor('pencil', {
  outline: 'black'
});

Try it now!

Overriding default options

The default values for all options are exposed by $.fn.awesomeCursor.defaults. This means you can easily override default options:

$.fn.awesomeCursor.defaults.color = 'white'; // Default color for all cursors is now white 

Using a different icon font

You may want to use an icon font other than FontAwesome for your cursors - this can be achieved using the font option (as of v0.1.0).

The font option is an object, containing the font family and cssClass. The example below demonstrates how to use typicons as the icon font:

$('body').awesomeCursor('brush', {
  font: {
    family: 'typicons',
    cssClass: 'typcn typcn-%s'
  }
});
  • The family option is the name of the font icon's family. For FontAwesome, it's 'FontAwesome'; for typicons it's 'typicons'
  • The cssClass option is the format of the replacement font icon's CSS classes, where %s is the name of the icon passed as the first parameter to awesomeCursor. You can also use a function instead of a string - the function receives the icon name as it's only parameter, and is expected to return the CSS class name for the icon, e.g.
    font: {
      family: 'typicons',
      cssClass: function(iconName) {
        return 'typcn typcn-' + iconName;
      }
    }

You can set an alternative font as the default in the same way you would override other defaults:

$.fn.awesomeCursor.defaults.font = {
  family: 'typicons',
  cssClass: 'typcn typcn-%s'
};

Examples

Hover your cursor over the boxes to see the example cursors

Blue Paper Plane With Top Right Hotspot

$('#example1')
  .awesomeCursor('paper-plane', {
    color: '#2cb2da',
    hotspot: 'top right'
  });

Big Green Paintbrush

$('#example2')
  .awesomeCursor('paint-brush', {
    color: '#34db33',
    size: 32
  });

Red Banned Circle With Centered Hotspot

$('#example3')
  .awesomeCursor('ban', {
    color: 'red',
    size: 24,
    hotspot: 'center'
  });

Pink Horizontally Flipped Fighter Jet

$('#example4')
  .awesomeCursor('fighter-jet', {
    color: 'hotpink',
    size: 24,
    flip: 'horizontal'
  });

Blue Rotated Hand

$('#example5')
  .awesomeCursor('hand-o-up', {
    color: 'skyblue',
    size: 24,
    rotate: 45
  });

Green Pencil With Brown Outline

$('#example6')
  .awesomeCursor('pencil', {
    color: 'limegreen',
    size: 24,
    outline: 'brown'
  });

<iframe>

Wait for the <iframe> to load, then set the cursor on the contents:

var $iframe = $('#iframe');
$iframe.ready(function(e) {
  $iframe.contents().find('img').awesomeCursor('map-marker', {
    color: 'maroon',
    size: 32,
    outline: '#ccc',
    hotspot: 'center bottom'
  });
});

Google Maps

Using the Google Maps Javascript API v3.

var map = new google.maps.Map($('#google-maps')[0], {
  center: { lat: 37.544494, lng: 138.276398 },
  zoom: 8
});

google.maps.event.addListenerOnce(map, 'bounds_changed', function() {
  $('#google-maps').find('div').awesomeCursor('location-arrow', {
    size: 22,
    color: 'orange',
    flip: 'horizontal'
  });
});