🎉
Vue Cursor Fx
An animated custom cursor effects for interactive elements like navigation - w/ VueJS - SSR Compatible
Installation
This package is available on npm and yarn.
# Deps
npm install --save @luxdamore/vue-cursor-fx
# Or
yarn add @luxdamore/vue-cursor-fx
Usage
As component
// Global component and css
import { CursorFx } from '@luxdamore/vue-cursor-fx';
import '@luxdamore/vue-cursor-fx/dist/CursorFx.css';
// Install
Vue.component(
CursorFx.name,
CursorFx
);
// Or, in a .vue file
import { CursorFx } from '@luxdamore/vue-cursor-fx';
export default {
components: {
'cursor-fx': CursorFx,
},
};
<style src="@luxdamore/vue-cursor-fx/dist/CursorFx.css"></style>
As a global plugin
// Plugin
import CursorFx from '@luxdamore/vue-cursor-fx';
import '@luxdamore/vue-cursor-fx/dist/CursorFx.css';
// Install
Vue.use(
CursorFx
);
Browser's way
<!doctype html>
<html>
<head>
<!-- CursorFx styles -->
<!-- Old way -->
<link rel="stylesheet" href="https://unpkg.com/@luxdamore/vue-cursor-fx@latest/dist/CursorFx.css" />
<!-- end old way -->
<!-- New way -->
<link rel="preload" href="https://unpkg.com/@luxdamore/vue-cursor-fx@latest/dist/CursorFx.css" as="style" onload="this.rel='stylesheet'" />
<link rel="preload" href="https://unpkg.com/@luxdamore/vue-cursor-fx@latest/dist/CursorFx.umd.min.js" as="script" />
<!-- end new way -->
<!-- end CursorFx styles -->
</head>
<body>
<!--
Others script (ex. VueJs) and html.
-->
<!-- CursorFx script -->
<script src="https://unpkg.com/@luxdamore/vue-cursor-fx@latest/dist/CursorFx.umd.min.js"></script>
<!-- end CursorFx script -->
</body>
</html>
Markup
Use one time in the main file of your project or in every views, where you want it.
<button
type="button"
title="Special button"
data-cursor-hover
>
Add `data-cursor-hover` to an every html elements that you want to see the cursor bigger on hover
</button>
<button
type="button"
title="Special button"
data-cursor-hidden
>
Add `data-cursor-hidden` to an every html elements that you want to hide the cursor on hover
</button>
<button
type="button"
title="Special button"
data-cursor-hover
data-cursor-mix-blend-mode="difference"
>
Add `data-cursor-mix-blend-mode` to an every html elements that you want to change the mix-blend-mode type.
</button>
<cursor-fx />
Options
N.B.: the cursor is not activated on touchscreen devices.
Slots
# Available
slot="default" # Add some content in the middle of the cursor
Events
<cursor-fx
@before-start="onBeforeStart"
@after-start="onAfterStart"
@ready="onReady"
@before-destroy="onBeforeDestroy"
@after-destroy="onAfterDestroy"
></cursor-fx>
Props
| Attribute | Type | Default value | About |
|---|---|---|---|
| config | Object | {} | The default options applied to cursor, see below the BASE_CONFIG |
| color | String | #333333 | Color for the cursor |
| color-hover | String | #333333 | Color, on hover, for the cursor |
| outside-size | String | null | The size of outer circle |
| inside-size | String | null | The size of inner dot |
| shape | String | null | Only available shapes are circle and square |
| delay | String, Number | 60 | Activate cursor after x seconds |
| mix-blend-mode | String | null | Set the global mix-blend-mode style |
| force-custom-slot | Boolean | false | Show or hide the internal default slot |
| allow-on-mobile | Boolean | false | Allow the cursor on mobile devices |
| hide-outside | Boolean | false | Hide outer circle |
| hide-inside | Boolean | false | Hide inner dot |
| disabled | Boolean | false | Disable the activation of the cursor |
const BASE_CONFIG = {
lerps: {
dot: 1,
circle: 0.18,
custom: 0.23,
},
scale: {
ratio: 0.18,
min: 0.5,
max: 1,
},
opacity: 0.1,
};
Methods
<!-- component.vue -->
<template>
<div>
<!-- start it, later -->
<cursor-fx ref="cursor" disabled />
</div>
</template>
<!-- Component -->
<script>
export default {
mounted() {
// start it, on mounted, or wherever you want
this.$refs.cursor.start();
},
methods: {
others() {
// destroy
this.$refs.cursor.destroy();
//-> refresh automate: `destroy()` and `start()`
this.$refs.cursor.refresh();
},
}
},
</script>
Integrations
VueRouter
<!-- App.vue -->
<template>
<div>
<router-view></router-view>
<cursor-fx ref="cursor" />
</div>
</template>
NuxtJs
- For the entire website: place the component in the desired layouts (ex. layouts/default.vue);
- For some pages only: place the component in the desired pages (ex. pages/index.vue).
<!-- layout/default.vue -->
<template>
<div>
<main>
<nuxt />
</main>
<cursor-fx ref="cursor" />
</div>
</template>
Tips
- Q: How to fix problem with the disappearance of the cursor on nuxt route change ?
- A: Trigger cursor refresh on route change where component is placed.
watch: {
$route( to, from ) {
this.$nextTick( () => this.$refs.cursor.refresh() );
},
},
👩🏻💻👨🏻💻 Development
- Clone the repository:
git clone https://github.com/LuXDAmore/vue-cursor-fx.git;
- Install dependencies:
yarn install(ornpm install);
- Start a development server:
yarn dev(ornpm run dev);
- Extra, build the documentation (Github Pages):
yarn build(ornpm run build);- the content is automatically generated into the
/docsfolder.
🐞
Issues
Please make sure to read the issue reporting checklist before opening an issue. Issues not conforming to the guidelines may be closed immediately.
📝
Discussions
We're using Github discussions as a place to connect with other members of our community. You are free to ask questions and share ideas, so enjoy yourself.
👥
Contribution
Please make sure to read the contributing guide before making a pull request.
📖
Changelog
Details changes for each release are documented in the release notes.
🆓
License
MIT License // Copyright (©) 2019-now Luca Iaconelli
💼
Hire me
💸
Are you feeling generous today?
If You want to share a beer, we can be really good friends
☀ It's always a good day to be magnanimous - cit.
💡
Lighthouse
10 Oct 7, 2022
64 Dec 16, 2022
94 Nov 11, 2022
4k Jan 1, 2023
4.7k Jan 4, 2023
22.7k Jan 9, 2023
2 Jan 20, 2022
22k Jan 4, 2023
16.5k Jan 8, 2023
113 Jan 8, 2023
9 Mar 11, 2022
176 Jan 2, 2023
80.1k Dec 31, 2022
4k Dec 30, 2022
84 Nov 28, 2022
63 Dec 30, 2022
6 Jun 25, 2022
187 Jan 2, 2023
2 Jan 6, 2022