@namchee/tetikus

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

Table of Contents

• Features
• Installation
• Usage
• Props
• Slots
• Events
• Directives
• Options
• Objects
• Development
• License

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.

Development

Make sure that your have NodeJS and npm installed in your computer!

1. Clone this repository
2. Navigate to the project directory
3. Install all required dependency by executing npm install from your terminal
4. Link the project with the playground
5. Execute npm run build:watch from your terminal
6. Happy developing!

License

This project is licensed under MIT License