Options

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

type: String

The first parameter to awesomeCursor is the icon name.


{% highlight javascript %}$('body').awesomeCursor('pencil');{% endhighlight %}

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.

{% highlight javascript %}$('body').awesomeCursor('pencil', { color: 'red' });{% endhighlight %}

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


{% highlight javascript %}$('body').awesomeCursor('pencil', { size: 32 });{% endhighlight %}

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

{% highlight javascript %}$('body').awesomeCursor('pencil', { hotspot: [5, 7] });{% endhighlight %}
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'

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

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.


{% highlight javascript %}$('body').awesomeCursor('pencil', { flip: 'horizontal' });{% endhighlight %}

Try it now!

type: Number

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


{% highlight javascript %}$('body').awesomeCursor('pencil', { rotate: 45 });{% endhighlight %}

Try it now!

type: String

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


{% highlight javascript %}$('body').awesomeCursor('pencil', { outline: 'black' });{% endhighlight %}

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:

{% highlight javascript %}$.fn.awesomeCursor.defaults.color = 'white'; // Default color for all cursors is now white {% endhighlight %}

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: {% highlight javascript %}$('body').awesomeCursor('brush', { font: { family: 'typicons', cssClass: 'typcn typcn-%s' } });{% endhighlight %}

  • 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. {% highlight javascript %} font: { family: 'typicons', cssClass: function(iconName) { return 'typcn typcn-' + iconName; } } {% endhighlight %}

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

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