Skip to content

πŸ–± An animated custom cursor effects for interactive elements like navigation - w/ VueJS - SSR Compatible

License

Notifications You must be signed in to change notification settings

LuXDAmore/vue-cursor-fx

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

πŸŽ‰ Vue Cursor Fx

Code Quality Downloads Dependencies Version Donate

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

  1. Clone the repository:
    • git clone https://github.com/LuXDAmore/vue-cursor-fx.git;
  2. Install dependencies:
    • yarn install (or npm install);
  3. Start a development server:
    • yarn dev (or npm run dev);
  4. Extra, build the documentation (Github Pages):
    • yarn build (or npm run build);
    • the content is automatically generated into the /docs folder.

🐞 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

Contacts

πŸ’Έ Are you feeling generous today?

If You want to share a beer, we can be really good friends πŸ˜„

Paypal // Patreon // Ko-fi

β˜€ It's always a good day to be magnanimous - cit.


πŸ’‘ Lighthouse

Lighthouse audit score


πŸ’˜ Inspired by

CustomCursors by Tympanus