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