@namchee/tetikus NPM

Tetikus

Tetikus is a custom cursor component made for Vue 3 🖱️.

⚠️ WARNING: This component DOES NOT WORK with Vue 2! Consider upgrading to Vue 3 as it's already been officially released.
⚠️ WARNING: This library DOES NOT work on older browsers that doesn't support esnext, the reason is stated here

Features

Easily customizable, you're not locked with basic circle shape and most events are emitted properly
Relatively performant, uses native browser technologies
Relatively small, the minified build is only 6.3KB gzipped 📦
Made with Typescript, no more guessing games 🤔
Depends on nothing, all features are implemented with pure CSS, JS, and Vue ✌️.

Installation

Simply execute this script from your terminal

npm install @namchee/tetikus --save

After that, you can add it to your Vue 3 application by using the .use() like:

import { createApp } from 'vue';
import Root from './Root.vue';
import Tetikus from '@namchee/tetikus';
import '@namchee/tetikus/dist/tetikus.css';

const app = createApp(Root);
app.use(Tetikus);

Usage

Just use the component in your root file. You can use the directives on any element in your app.

// Root.vue
<template>
  <div>
    <tetikus />
  </div>
</template>

// ...rest of your code

// Somewhere.vue
<template>
  <div v-thover="{ scale: 0.8 }">
    // ...
  </div>
</template>

// If you're not using the global installation method,
// make sure to install the components and directives correctly

Props

Prop Name	Type	Default	Description
`showDefaultCursor`	`boolean`	`false`	Determines if the native cursor should be shown alongside `tetikus` component. Useful for accessability purposes.
`throttleSpeed`	`number` (integer)	1	Number of `mousemove` event that should be fired per 1000 milliseconds. The higher the number, the choppier the cursor movement will be. Useful to boost performance.
`borderWidth`	`number` (px)	2	Border width of default cursor shape in pixels.
`color`	`string`	`transparent`	Background color of default cursor shape. Accept any CSS color value.
`borderColor`	`string`	`#121212`	Border color of default cursor shape. Accept any CSS color value.
`size`	`number` (px)	36	Size of default cursor shape in pixels
`invertColor`	`boolean`	`false`	Determines if the default cursor shape should apply `mix-blend-mode: difference`
`buttonMap`	`Array`	`['left']`	List of mouse button that should trigger `tetikus-mouse-down` event. Possible values are `left`, `right`, `middle`
`clickBehavior`	`TransformProps`	`{}`	Determines transforms that should be applied to default cursor when a click event is registered
`showOnTouch`	`boolean`	`false`	Determines if the cursor should be shown on 'touch'-devices. ⚠️ Unless you know what are you doing, leave this on `false` ⚠️
`opacity`	`number` (between 0.0 - 1.0)	1	Opacity of default cursor.
`hideOnOut`	`boolean`	`false`	Determines if the custom cursor should be hidden when the cursor leaves the viewport
`contentPosition`	`string`	`center`	Determines the position of `contents` slot relative to the cursor. Possible values are `center`, `bottom`, `right`
`lerp`	`number`	`1`	Linear Interpolation Value
`options`	`Object`	`{}`	All of other options in one single object. Will gracefully fallback if some values are not provided.

Slots

Name	Description
(default slot)	Determines the cursor shape to be used. The default shape is a perfect circle ⚠️ Currently, using this slot will render any previously defined behaviors invalid. Any transition MUST be handled by yours truly ⚠️
`contents`	Content to be displayed with the cursor

Events

Name	Params	Description
`tetikus-window-leave`		Fired when the cursor leaves the viewport
`tetikus-window-enter`		Fired when the cursor enters the viewport
`tetikus-mouse-move`	`(event: MouseEvent)`	Fired when the cursor moves on the viewport
`tetikus-mouse-down`	`(event: MouseEvent)`	Fired when any previously registered mouse buttons are clicked by the user
`tetikus-mouse-up`	`(event: MouseEvent)`	Fired when any previously registered mouse buttons are lifted
`tetikus-element-in`	`(behavior: HoverBehavior)`	Fired when the cursor hovers over any element that has `tetikus` hover directives
`tetikus-element-out`	`(behavior: HoverBehavior)`	Fired when the cursor exits from the bounding box of any element that has `tetikus` hover directives

Directives

Name	Value	Description
`thover` (can be customized from options)	`TransformProps`	Determines transform to be applied when the cursor hovers this element

Component Options

These values will set default values for tetikus component

Name	Type	Default	Description
`directiveName`	`string`	`thover`	Name for the hover directive.
`transitionSpeed`	`number` (ms)	200	Animation speed for CSS transition.
`easing`	`string`	`ease-out`	Easing function for CSS transition. Accept anything than can be represented using `cubic-bezier`
`delay`	`number` (ms)	0	Delay for CSS transition.

Objects

Name	Property	Type	Description
`TransformOpts`	`value`	`T`	Value for the transformation.
	`duration` (optional)	`number` (ms)	Transition duration. If the value is omitted, default value will be used
	`delay` (optional)	`number` (ms)	Delay for CSS transition.
	`easing` (optional)	`string`	Easing function for CSS transition. Accept anything than can be represented using `cubic-bezier`
`TransformProps`	`scale` (optional)	`TransformOpts<number>`, `number`	Determines the scale of cursor to be applied on transition.
	`color` (optional)	`TransformOpts<string>`, `string`	Determines the background color of cursor to be applied on transition.
	`borderWidth` (optional)	`TransformOpts<number>`, `number`	Determines the border width of cursor to be applied on transition.
	`borderColor` (optional)	`TransformOpts<string>`, `string`	Determines the border color of cursor to be applied on transition. Accepts any CSS color string.
	`opacity` (optional)	`TransformOpts<number>`, `number` (between 0.0 - 1.0)	Determines the opacity of cursor to be applied on transition.
	`id` (optional)	`string`, `string[]`	Specify instances which should transform on hover event. Useful when you have multiple `tetikus` instances. Won't work at all on click events, you must register different behaviors directly into the instances.
`HoverBehavior`	`domElement`	`HTMLElement`	The HTML element that triggers `tetikus-element-in` and `tetikus-element-out` events.
	`transformProps`	`TransformProps`	Transformation to be applied on the cursor element.

Note: When any property of TransformProps is defined without TransformOpts, the transition settings (duration, easing, delay) for that property will be applied with default values.