ITC Hover Package

A flexible hover and tooltip component for Vue 3 + Quasar applications. Easily add tooltips to any element with full control over positioning, styling, delay, and behavior using Quasar's powerful tooltip system.

Features

• ✅ Vue 3 with Composition API
• ✅ Quasar Framework integration - Uses Quasar's q-tooltip component
• ✅ Simple API - Just wrap your element and pass props
• ✅ Flexible Positioning - Control anchor, self, offset with 9 position options
• ✅ Custom Styling - Custom classes, styles, and transitions
• ✅ HTML Support - Render HTML content in tooltips
• ✅ Delay Control - Custom delay before showing tooltip
• ✅ All Quasar Tooltip Props - Support for all Quasar tooltip features
• ✅ Dual Format Build - ES Modules and CommonJS

Philosophy

Props-Based Configuration:

Hover Component → Quasar q-tooltip → Rendered Tooltip

Instead of manually configuring Quasar tooltips, wrap your elements with Hover component and pass props to control all tooltip behavior.

Getting Started

Prerequisites

• Node.js 18+ or 20+
• npm or pnpm
• Vue 3.5.25+
• Quasar 2.18.6+

Installation

1. Install the package:

   npm install itc-hover
   # or
   pnpm add itc-hover

2. Use in your project:

   <script setup>
   import { Hover } from 'itc-hover'
   </script>
      
   <template>
     <Hover text="This is a tooltip">
       <q-btn label="Hover me" />
     </Hover>
   </template>

Usage

Basic Example

<template>
  <Hover text="Help information">
    <q-btn icon="help_outline" flat round />
  </Hover>
</template>

<script setup>
import { Hover } from 'itc-hover'
</script>

With Positioning

<template>
  <Hover
    text="Click to change tag"
    anchor="bottom right"
    self="top right"
  >
    <q-chip label="Tag" />
  </Hover>
</template>

With HTML Content

<template>
  <Hover
    text="Click to change <strong>'Tag Name'</strong> tag"
    :html="true"
    anchor="bottom right"
    self="top right"
  >
    <q-chip label="HTML Tag" />
  </Hover>
</template>

With Custom Delay

<template>
  <Hover
    text="This tooltip appears after 1 second"
    :delay="1000"
  >
    <q-btn label="Delayed Tooltip" />
  </Hover>
</template>

With Custom Styling

<template>
  <Hover
    text="Points Information"
    tooltip-class="bg-grey-9"
    transition-show="scale"
    transition-hide="scale"
  >
    <q-btn icon="info" />
  </Hover>
</template>

API Reference

Hover Component Props

Content Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | text | String | null | Tooltip text content (alternative to tooltip) | | tooltip | String | null | Tooltip text content (alternative to text) | | html | Boolean | false | Render text as HTML (alternative to tooltipHtml) | | tooltipHtml | Boolean | false | Render text as HTML (alternative to html) | | showTooltip | Boolean | true | Show/hide tooltip |

Positioning Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | anchor | String | undefined | Position of tooltip relative to trigger (alternative to tooltipAnchor) | | tooltipAnchor | String | 'bottom middle' | Position of tooltip relative to trigger (alternative to anchor) | | self | String | undefined | Position of tooltip itself (alternative to tooltipSelf) | | tooltipSelf | String | 'top middle' | Position of tooltip itself (alternative to self) | | offset | Array | undefined | Offset [x, y] in pixels (alternative to tooltipOffset) | | tooltipOffset | Array | [10, 10] | Offset [x, y] in pixels (alternative to offset) |

Valid Anchor/Self Values:

• 'top left', 'top middle', 'top right'
• 'center left', 'center middle', 'center right'
• 'bottom left', 'bottom middle', 'bottom right'

Behavior Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | delay | Number | undefined | Delay before showing tooltip in milliseconds (alternative to tooltipDelay) | | tooltipDelay | Number | undefined | Delay before showing tooltip in milliseconds (alternative to delay) | | maxWidth | String | undefined | Maximum width of tooltip (alternative to tooltipMaxWidth) | | tooltipMaxWidth | String | '200px' | Maximum width of tooltip (alternative to maxWidth) | | transitionShow | String | undefined | Transition when showing (alternative to tooltipTransitionShow) | | tooltipTransitionShow | String | 'fade' | Transition when showing (alternative to transitionShow) | | transitionHide | String | undefined | Transition when hiding (alternative to tooltipTransitionHide) | | tooltipTransitionHide | String | 'fade' | Transition when hiding (alternative to transitionHide) |

Styling Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | tooltipClass | String | '' | Additional CSS class for tooltip | | style | String/Object | {} | Inline styles for tooltip (alternative to tooltipStyle) | | tooltipStyle | String/Object | {} | Inline styles for tooltip (alternative to style) |

Advanced Quasar Tooltip Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | noParentEvent | Boolean | false | Prevent tooltip from closing when clicking parent | | tooltipNoParentEvent | Boolean | false | Prevent tooltip from closing when clicking parent | | fit | Boolean | false | Fit tooltip within viewport | | tooltipFit | Boolean | false | Fit tooltip within viewport | | cover | Boolean | false | Tooltip covers the target element | | tooltipCover | Boolean | false | Tooltip covers the target element | | persistent | Boolean | false | Tooltip stays visible until manually closed | | tooltipPersistent | Boolean | false | Tooltip stays visible until manually closed | | scrollTarget | String/Object | undefined | Custom scroll target element/selector | | tooltipScrollTarget | String/Object | undefined | Custom scroll target element/selector | | touchPosition | Boolean | false | Use touch position on mobile devices | | tooltipTouchPosition | Boolean | false | Use touch position on mobile devices |

Slots

| Slot | Description | |------|-------------| | default | Element to wrap with tooltip |

Examples

Simple Button Tooltip

<template>
  <Hover text="Time Entries">
    <q-btn icon="o_timer" flat round />
  </Hover>
</template>

<script setup>
import { Hover } from 'itc-hover'
</script>

Chip with Tag Change Tooltip

<template>
  <Hover
    text="Click to change 'Tag Name' tag"
    :html="true"
    anchor="bottom right"
    self="top right"
  >
    <q-chip label="Tag" />
  </Hover>
</template>

<script setup>
import { Hover } from 'itc-hover'
</script>

Icon with Dynamic Tooltip

<template>
  <Hover :text="user.email">
    <q-btn icon="email" flat round />
  </Hover>
</template>

<script setup>
import { Hover } from 'itc-hover'
import { ref } from 'vue'

const user = ref({ email: '[email protected]' })
</script>

Dark Background Tooltip

<template>
  <Hover
    text="Change Image"
    tooltip-class="bg-dark"
  >
    <q-btn icon="image" />
  </Hover>
</template>

<script setup>
import { Hover } from 'itc-hover'
</script>

Scale Transition Tooltip

<template>
  <Hover
    text="Points Information"
    tooltip-class="bg-grey-9"
    transition-show="scale"
    transition-hide="scale"
    anchor="bottom middle"
    self="bottom middle"
  >
    <q-btn icon="info" />
  </Hover>
</template>

<script setup>
import { Hover } from 'itc-hover'
</script>

With Custom Delay and Offset

<template>
  <Hover
    text="This tooltip appears after 1 second"
    :delay="1000"
    :offset="[20, 20]"
  >
    <q-btn label="Delayed Tooltip" />
  </Hover>
</template>

<script setup>
import { Hover } from 'itc-hover'
</script>

Persistent Tooltip

<template>
  <Hover
    text="This tooltip stays visible"
    :persistent="true"
  >
    <q-btn label="Persistent Tooltip" />
  </Hover>
</template>

<script setup>
import { Hover } from 'itc-hover'
</script>

Building

Build for Production

BUILD_LIB=true npm run build
# or
BUILD_LIB=true pnpm run build

This will:

• Compile JavaScript
• Bundle Vue components
• Generate both ES Modules (.js) and CommonJS (.cjs) formats
• Output to dist/ directory

Build Output Structure

dist/
├─ itc-hover.js      # ES Module
└─ itc-hover.cjs     # CommonJS

Development Build (Watch Mode)

BUILD_LIB=true npm run dev

Changes will rebuild automatically. Restart your test project's dev server to pick up changes.

Testing Locally

Option 1: Using npm link

1. In your package directory:

   npm link

2. In your test project:

   npm link itc-hover

Option 2: Using File Path

1. In your test project's package.json:

   {
     "dependencies": {
       "itc-hover": "file:../itc-hover"
     }
   }

2. Install:

   npm install

Development Workflow

For active development with auto-rebuild:

BUILD_LIB=true npm run dev

Changes will rebuild automatically. Restart your test project's dev server to pick up changes.

Publishing to npm

Before Publishing

1. Update package.json:

   • Verify name is unique on npm
   • Update version (follow semver)
   • Verify files array includes only dist:

     {
       "files": ["dist"]
     }

2. Build the package:

   BUILD_LIB=true npm run build

3. Test the build locally (see Testing Locally section above)

Publishing Steps

Step 1: Enable 2FA or Create Access Token

Option A: Enable 2FA on npm (Recommended)

1. Go to https://www.npmjs.com/settings/itcroja/security
2. Enable Two-Factor Authentication (2FA)
3. Follow the setup process (use authenticator app like Google Authenticator)
4. Once enabled, you can publish with 2FA code

Option B: Create Granular Access Token (Alternative)

1. Go to https://www.npmjs.com/settings/itcroja/tokens

2. Click Generate New Token → Granular Access Token

3. Set permissions:

   • Type: Automation
   • Packages: Select itc-hover or all packages
   • Permissions: Read and Write
   • Expiration: Set as needed

4. Copy the token (starts with npm_)

5. Use token for authentication:

   npm config set //registry.npmjs.org/:_authToken YOUR_TOKEN_HERE

Step 2: Login to npm

npm login

If using 2FA, you'll be prompted for the 2FA code during login.

Step 3: Verify you're logged in

npm whoami

Step 4: Check what will be published

npm pack --dry-run

Step 5: Publish

npm publish --access public

Note: If you have 2FA enabled, you may need to use npm publish --otp=YOUR_2FA_CODE or set up automation token.

5. Verify on npm: Visit https://www.npmjs.com/package/itc-hover

Version Management

Use npm version commands to bump versions:

# Patch version (1.0.0 → 1.0.1)
npm version patch

# Minor version (1.0.0 → 1.1.0)
npm version minor

# Major version (1.0.0 → 2.0.0)
npm version major

Then publish:

npm publish --access public

Configuration

External Dependencies

By default, vue and quasar are marked as external (not bundled). The package expects these to be provided by the consuming application.

Quasar Components Required

Ensure QTooltip component is registered in your Quasar config:

// quasar.config.js
framework: {
  components: [
    'QTooltip'
  ]
}

Best Practices

• ✅ Use peer dependencies for Vue and Quasar (provided by consumer)
• ✅ Use text prop for simple tooltips (shorter syntax)
• ✅ Use html prop when you need HTML formatting in tooltip
• ✅ Set appropriate delays for better UX (default 500ms works well)
• ✅ Use positioning props (anchor, self) for better tooltip placement
• ✅ Leverage Quasar classes for styling via tooltip-class prop
• ❌ Don't bundle Vue or Quasar into the package
• ❌ Don't use both text and tooltip props at the same time (use one)
• ❌ Don't use both html and tooltipHtml props at the same time (use one)

Troubleshooting

Component Not Found Errors

• "Failed to resolve component: q-tooltip": Register QTooltip component in quasar.config.js

Build Errors

• "Rollup failed to resolve import": Add the package to external in vite.config.ts
• "Cannot find module": Ensure package is built (BUILD_LIB=true npm run build)

Import Errors in Test Project

• Ensure the package is built (BUILD_LIB=true npm run build)
• Check package.json exports are correct
• Verify the import path matches your exports
• Clear node_modules and reinstall

Tooltip Not Showing

• Verify text or tooltip prop is provided
• Check that showTooltip is not false
• Ensure Quasar QTooltip component is registered
• Check browser console for errors

Delay Not Working

• Ensure you're using Quasar's default delay behavior (no manual implementation needed)
• Check that delay value is a number (in milliseconds)
• Verify tooltip is not being blocked by other elements

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Build and test locally
5. Submit a pull request

Happy coding! 🚀