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

$3

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

$3

1. Install the package:

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

2. Use in your project:

`vue



`

Usage

$3

`vue



`

$3

`vue

`

$3

`vue

`

$3

`vue

`

$3

`vue

`

API Reference

$3

#### 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 |

$3

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

Examples

$3

`vue



`

$3

`vue



`

$3

`vue



`

$3

`vue



`

$3

`vue



`

$3

`vue



`

$3

`vue



`

Building

$3

`bash
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

$3

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

$3

`bash
BUILD_LIB=true npm run dev
`

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

Testing Locally

$3

1. In your package directory:

`bash
npm link
`

2. In your test project:

`bash
npm link itc-hover
`

$3

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

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

2. Install:

`bash
npm install
`

$3

For active development with auto-rebuild:

`bash
BUILD_LIB=true npm run dev
`

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

Publishing to npm

$3

1. Update package.json:
- Verify name is unique on npm
- Update version (follow semver)
- Verify files array includes only dist:
`json
{
"files": ["dist"]
}
`

2. Build the package:

`bash
BUILD_LIB=true npm run build
`

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

$3

#### 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:

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

#### Step 2: Login to npm

`bash
npm login
`

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

#### Step 3: Verify you're logged in

`bash
npm whoami
`

#### Step 4: Check what will be published

`bash
npm pack --dry-run
`

#### Step 5: Publish

`bash
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

$3

Use npm version commands to bump versions:

`bash


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:

`bash
npm publish --access public
`

Configuration

$3

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

$3

Ensure QTooltip component is registered in your Quasar config:

`javascript
// 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

$3

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

$3

- "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)

$3

- 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

$3

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

$3

- 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! 🚀