hover-it

A Svelte component that displays a customizable label following the mouse cursor when hovering over elements with a data-cursor-label attribute.

Features

• 🖱️ Follows mouse cursor with smooth transitions
• 📱 Automatically hides on touch devices (coarse pointers)
• 🎯 Shows only on elements with data-cursor-label attribute
• 🎨 Customizable styling via CSS class prop
• 🔌 Optional integration with Svelte stores (e.g., for hiding during drag operations)
• ⚡ Lightweight with no external dependencies (except Svelte)

Installation

npm install hover-it

Usage

Basic

<script>
  import { MouseCursorLabel } from 'hover-it';
</script>

<MouseCursorLabel />

<!-- Add data-cursor-label to any element -->
<button data-cursor-label="Click me">Hover over me</button>
<a href="/" data-cursor-label="Go home">Home</a>

With Custom Styling

<script>
  import { MouseCursorLabel } from 'hover-it';
</script>

<MouseCursorLabel class="my-custom-class" />

<style>
  :global(.my-custom-class) {
    background-color: #333;
    color: white;
    border-radius: 4px;
  }
</style>

With Drag Detection (Store)

<script>
  import { MouseCursorLabel } from 'hover-it';
  import { writable } from 'svelte/store';

  const isDragging = writable(false);

  function handleDragStart() {
    isDragging.set(true);
  }

  function handleDragEnd() {
    isDragging.set(false);
  }
</script>

<MouseCursorLabel {isDragging} />

<div
  draggable="true"
  ondragstart={handleDragStart}
  ondragend={handleDragEnd}
  data-cursor-label="Drag me"
>
  Draggable element
</div>

With Drag Detection (Boolean)

<script>
  import { MouseCursorLabel } from 'hover-it';

  let isDragging = $state(false);
</script>

<MouseCursorLabel isDragging={isDragging} />

With Custom Offset

<MouseCursorLabel offset={{ x: 20, y: 20 }} />

Props

| Prop | Type | Default | Description | | ------------ | ------------------------------ | ------------------ | ------------------------------------------------------------- | | isDragging | Readable<boolean> \| boolean | false | When true, hides the cursor label. Can be a store or boolean. | | class | string | '' | Additional CSS class(es) applied to the label container. | | offset | { x: number, y: number } | { x: 14, y: 14 } | Offset from cursor position in pixels. | | debug | boolean | false | Enable console logging for debugging. |

Data Attributes

Add data-cursor-label to any element to show a label on hover:

<button data-cursor-label="Save changes">Save</button>

The label text supports HTML entities (e.g., %20 will be replaced with -).

Styling

The component uses scoped styles with a default appearance. You can override styles using the class prop with :global() selectors or by targeting the .mouse-cursor-label class.

Default styles:

• White background with slight transparency (95%)
• Border radius: 9999px (pill shape)
• Shadow for depth
• Backdrop blur effect
• Hidden on coarse pointer devices (touchscreens)

Browser Support

• Chrome/Edge 88+
• Firefox 78+
• Safari 14+

Requires support for:

• CSS backdrop-filter
• Pointer events
• CSS custom properties

License

MIT