Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jwarby/jquery-awesome-cursor
jQuery plugin for using FontAwesome icons as custom CSS cursors
https://github.com/jwarby/jquery-awesome-cursor
List: jquery-awesome-cursor
Last synced: 5 days ago
JSON representation
jQuery plugin for using FontAwesome icons as custom CSS cursors
- Host: GitHub
- URL: https://github.com/jwarby/jquery-awesome-cursor
- Owner: jwarby
- License: mit
- Created: 2014-11-03T14:26:49.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2017-08-26T11:10:10.000Z (about 7 years ago)
- Last Synced: 2024-10-28T05:32:43.761Z (15 days ago)
- Language: JavaScript
- Homepage: https://jwarby.github.io/jquery-awesome-cursor/
- Size: 1.13 MB
- Stars: 179
- Watchers: 15
- Forks: 68
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# jQuery Awesome Cursor plugin [](http://badge.fury.io/gh/jwarby%2Fjquery-awesome-cursor)
[](https://travis-ci.org/jwarby/jquery-awesome-cursor)
[](https://david-dm.org/jwarby/jquery-awesome-cursor#info=peerDependencies)
[](https://david-dm.org/jwarby/jquery-awesome-cursor#info=devDependencies)
A jQuery plugin for using FontAwesome icons as custom CSS cursors. Also supports using a custom icon font instead of FontAwesome.
See for the full documentation and demos.
```javascript
$('body').awesomeCursor('pencil');
```
Requires [jQuery](http://jquery.com) and [FontAwesome](http://fontawesome.io).
## Getting started
### Installing the plugin
#### via `npm` (recommended)
```shell
npm install jquery-awesome-cursor
```
```html
```
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:
```shell
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`
```shell
bower install jquery-awesome-cursor
```
```html
```
##### 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](https://github.com/jwarby/jquery-awesome-cursor/issues/21).
```shell
bower install font-awesome
```
#### Manual installation
Download the [production version][min] or the [development version][max]. You will need to download and install FontAwesome manually as well.
[min]: https://raw.githubusercontent.com/jwarby/jquery-awesome-cursor/master/dist/jquery.awesome-cursor.min.js
[max]: https://raw.githubusercontent.com/jwarby/jquery-awesome-cursor/master/dist/jquery.awesome-cursor.js
In your web page:
```html
```
#### RawGit CDN
You could also use [RawGit](https://rawgit.com)'s CDN:
```html
```
## 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:
```javascript
$('body').awesomeCursor('');
```
See for a list of available icons.
### Setting cursor options
#### Colour
Cursors can be any color you want, specified as a CSS color:
```javascript
$('body').awesomeCursor('eyedropper', {
color: '#ff0000'
})
```
```javascript
$('body').awesomeCursor('eyedropper', {
color: 'rgba(255, 255, 255, 0.75)'
})
```
```javascript
$('body').awesomeCursor('eyedropper', {
color: 'cyan'
});
```
```javascript
$('body').awesomeCursor('eyedropper', {
color: 'hsl(90, 100%, 50%)'
});
```
#### Size
Cursors can be any size (specified in pixels):
```javascript
$('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:
```javascript
$('body').awesomeCursor('pencil', {
hotspot: [0, 17]
});
```
Or, using a string descriptor:
```javascript
$('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:
```javascript
// 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:
```javascript
// 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:
```javascript
// 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](http://typicons.com)
icons can be used instead of FontAwesome icons:
```javascript
// 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:
```javascript
// 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:
```javascript
// 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
```javascript
/* 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
- Chrome
- Firefox
## Bugs and Feature Requests
-
## Contributing
See [CONTRIBUTING.md](https://github.com/jwarby/jquery-awesome-cursor/blob/master/CONTRIBUTING.md)
## Roadmap
- ~~Allow cursors to be flipped vertically and/or horizontally~~ [✔ v0.0.2](https://github.com/jwarby/jquery-awesome-cursor/releases/tag/v0.0.2)
- ~~Allow cursors to be rotated by an abitrary number of degrees~~ [✔ v0.0.4](https://github.com/jwarby/jquery-awesome-cursor/releases/tag/v0.0.4)
- ~~Optional outlines for cursors~~ [✔ v0.0.5](https://github.com/jwarby/jquery-awesome-cursor/releases/tag/v0.0.5)
- ~~Allow a different icon font to FontAwesome to be used~~ [✔ v0.1.0](https://github.com/jwarby/jquery-awesome-cursor/releases/tag/v0.1.0)
- IE11 support (if possible)
- ~~Data API (under consideration)~~ [✕ Not implemented](https://github.com/jwarby/jquery-awesome-cursor/issues/6)
- ~~Support for composite cursors made of up of multiple icons, a la FontAwesome stacked icons (under consideration)~~ [✕ Not implemented](https://github.com/jwarby/jquery-awesome-cursor/issues/7)
## Release History
- `v0.3.1` - `23rd Apr 2016` - Hotfix - change TravisCI node test versions to v4 and v5; add dotfiles back into bower ignore field
- `v0.3.0` - `23rd Apr 2016` - Make FontAwesome an optional dependency ([#21](https://github.com/jwarby/jquery-awesome-cursor/issues/21)); add an .npmignore file, update bower ignore field; updated devDependencies
- `v0.2.0` - `28th Mar 2016` - Bug fix for certain icons getting clipped when used as a cursor ([#19](https://github.com/jwarby/jquery-awesome-cursor/issues/19))
- `v0.1.5` - ` 9th Dec 2015` - Add `main` to package.json, allowing plugin to be used properly when installed via npm and used with tools such as Browserify
- `v0.1.4` - `23rd Oct 2015` - Remove minor version constraints on bower/npm dependencies
- `v0.1.3` - `19th Oct 2015` - Bug fix for Chrome not updating cursor if cursor had already been set, run tests using Karma, using SPDX format for "license" field in package.json
- `v0.1.2` - `25th May 2015` - Bug fix for rendering artifacts in Chrome ([#14](https://github.com/jwarby/jquery-awesome-cursor/issues/14))
- `v0.1.1` - ` 5th Mar 2015` - Bug fix for rendering artifacts in Firefox ([#10](https://github.com/jwarby/jquery-awesome-cursor/issues/10))
- `v0.1.0` - `17th Dec 2014` - Add `font` option for specifying an alternative icon font to use instead of FontAwesome
- `v0.0.5` - `12th Dec 2014` - Add `outline` option for specifying an outline color for cursors
- `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