search

jwarby / jquery-awesome-cursor

jQuery plugin for using FontAwesome icons as custom CSS cursors
https://jwarby.github.io/jquery-awesome-cursor/
MIT License
179 stars 69 forks source link

readme

jQuery Awesome Cursor plugin GitHub version

Build Status Dependency Status devDependency Status

A jQuery plugin for using FontAwesome icons as custom CSS cursors. Also supports using a custom icon font instead of FontAwesome.

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 npm (recommended)

npm install jquery-awesome-cursor
<link rel="stylesheet" href="https://github.com/jwarby/jquery-awesome-cursor/blob/master/node_modules/font-awesome/css/font-awesome.min.css" type="text/css">
<script src="https://github.com/jwarby/jquery-awesome-cursor/raw/master/node_modules/jquery/dist/jquery.min.js" type="text/javascript"></script>
<script src="https://github.com/jwarby/jquery-awesome-cursor/raw/master/node_modules/jquery-awesome-cursor/dist/jquery.awesome-cursor.min.js" type="text/javascript"></script>

From v0.3.0 onwards, FontAwesome is marked as an optional dependency. If you plan on using jquery-awesome-cursor with a different icon font, you can skip installation of any optional dependencies like this:

npm install --no-optional jquery-awesome-cursor
IMPORTANT: npm@3 won't install peerDependencies anymore, so if you haven't already installed jQuery you will get an UNMET PEER DEPENDENCY warning when you install. To fix, just do npm install jquery.

via bower

bower install jquery-awesome-cursor
<link rel="stylesheet" href="https://github.com/jwarby/jquery-awesome-cursor/blob/master/bower_components/fontawesome/css/font-awesome.min.css" type="text/css">
<script src="https://github.com/jwarby/jquery-awesome-cursor/raw/master/bower_components/jquery/dist/jquery.min.js" type="text/javascript"></script>
<script src="https://github.com/jwarby/jquery-awesome-cursor/raw/master/bower_components/jquery-awesome-cursor/dist/jquery.awesome-cursor.min.js" type="text/javascript"></script>
IMPORTANT: from v0.3.0 onwards, you need to bring your own FontAwesome! FontAwesome is considered an optional dependency, but Bower doesn't support optional dependencies - so you must install FontAwesome yourself. See #21.
bower install font-awesome

Manual installation

Download the production version or the development version. You will need to download and install FontAwesome manually as well.

In your web page:

<link rel="stylesheet" href="https://github.com/jwarby/jquery-awesome-cursor/blob/master/path/to/font-awesome.min.css" type="text/css">
<script src="https://github.com/jwarby/jquery-awesome-cursor/raw/master/path/to/jquery.js"></script>
<script src="https://github.com/jwarby/jquery-awesome-cursor/raw/master/path/to/jquery.awesome-cursor.min.js"></script>

RawGit CDN

You could also use RawGit's CDN:

<link rel="stylesheet" href="https://github.com/jwarby/jquery-awesome-cursor/blob/master/path/to/font-awesome.min.css" type="text/css">
<script src="https://github.com/jwarby/jquery-awesome-cursor/raw/master/path/to/jquery.js"></script>
<script src="https://cdn.rawgit.com/jwarby/jquery-awesome-cursor/master/dist/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:

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

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
});

Outline

A cursor can be outlined in any color by setting the outline option to any valid CSS color:

// Red outline
$('body').awesomeCursor('pencil', {
  outline: 'red'
});

// White outline
$('body').awesomeCursor('pencil', {
  outline: 'white'
});

Using a different icon font

As of v0.1.0, a different icon font instead of FontAwesome can be used. To use a different font, the font option must be set to an object, specifying the font family and the CSS class format for icons. The example below shows how typicons icons can be used instead of FontAwesome icons:

// Using 'typicons' icons instead of FontAwesome
$('body').awesomecursor('brush', {
  font: {
    family: 'typicons',
    cssClass: 'typcn typcn-%s' // '%s' is the icon name ('brush')
  }
});

In the above example, we set the font family to 'typicons', and set the cssClass to the format that typicons uses. %s denotes the icon name that is passed as the first argument to awesomeCursor.

The cssClass option can either be a string, as shown above, or a function:

// Using 'typicons' instead of fontawesome
$('body').awesomecursor('brush', {
  font: {
    family: 'typicons',
    cssClass: function(name) {

      // `name` is 'brush'
      return 'typcn typcn-' + name;
    }
  }
});

You may want to set your replacement icon font as the default:

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

Note: the replacement icon font must use :before pseudo elements with unicode content

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'
});

// Set the cursor to be a red rotated left arrow
$('body').awesomeCursor('long-arrow-left', {
  color: 'red',
  hotspot: 'top left',
  rotate: 45,
});

// Set the cursor to a black eraser icon with a red outline
$('body').awesomeCursor('eraser', {
  color: 'black',
  outline: 'red'
});

Browser Support

Bugs and Feature Requests

Contributing

See CONTRIBUTING.md

Roadmap

Release History