@amplydevteam/tooltip

v0.0.2

Published

a month ago

A zero-config, attribute-based tooltip library for Webflow

0High
0Medium
0Low

amplyteam

tooltip popover dropdown webflow typescript

Amply Tooltip

A zero-config, attribute-based tooltip library for Webflow.

Installation

CDN (Webflow)

Add to your project's custom code:

<!-- In <head> -->
<link
  rel="stylesheet"
  href="https://unpkg.com/@amplydevteam/tooltip/dist/tooltip.css"
/>

<!-- Before </body> -->
<script
  type="module"
  src="https://unpkg.com/@amplydevteam/tooltip/dist/tooltip.js"
></script>

NPM

npm install @amplydevteam/tooltip

import "@amplydevteam/tooltip";

Usage

Just add attributes to any element. Tooltips auto-initialize on page load.

<button amply-tooltip amply-tooltip-text="Hello!">
  Hover me
</button>

Attributes

Core

| Attribute | Description | Example | | -------------------- | ------------------------------- | -------------------------------------------- | | amply-tooltip | Marks element as tooltip target | amply-tooltip | | amply-tooltip-text | Plain text content | amply-tooltip-text="Hello" | | amply-tooltip-html | HTML content (entities decoded) | amply-tooltip-html="<strong>Bold</strong>" |

Note: HTML entities in amply-tooltip-html are automatically decoded for safety. Use " for quotes, < for <, > for >.

<button amply-tooltip-html='Say "Hello"'>Hover</button>

Position

| Attribute | Values | Default | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | amply-tooltip-placement | top, top-start, top-end, bottom, bottom-start, bottom-end, left, left-start, left-end, right, right-start, right-end | top | | amply-tooltip-offset | 0 - 100 (pixels) | 10 |

Appearance

| Attribute | Values | Default | | ------------------------- | ---------------------- | ------- | | amply-tooltip-theme | dark, light | dark | | amply-tooltip-arrow | true, false | true | | amply-tooltip-max-width | 50 - 1000 (pixels) | 350 |

Animation

| Attribute | Values | Default | | ------------------------- | --------------------------------------------- | ------- | | amply-tooltip-animation | fade, scale, shift-away, shift-toward | fade | | amply-tooltip-duration | 0 - 2000 (ms) | 200 | | amply-tooltip-delay | 0 - 5000 (ms) | 0 |

Behavior

| Attribute | Values | Default | | ----------------------------- | ----------------------------------- | ------- | | amply-tooltip-trigger | hover, click, focus, manual | hover | | amply-tooltip-interactive | true, false | false | | amply-tooltip-hide-on-click | true, false | true |

Examples

Basic

<button amply-tooltip amply-tooltip-text="Simple tooltip">
  Hover me
</button>

Positioned

<button
  amply-tooltip
  amply-tooltip-text="I'm on the bottom!"
  amply-tooltip-placement="bottom"
>
  Bottom tooltip
</button>

Styled

<button
  amply-tooltip
  amply-tooltip-text="Light theme tooltip"
  amply-tooltip-theme="light"
  amply-tooltip-animation="scale"
>
  Light & animated
</button>

Click trigger

<button
  amply-tooltip
  amply-tooltip-text="Click to toggle!"
  amply-tooltip-trigger="click"
>
  Click me
</button>

Interactive with HTML

<span
  amply-tooltip
  amply-tooltip-html="<strong>Rich</strong> content with <em>HTML</em>"
  amply-tooltip-interactive="true"
  amply-tooltip-max-width="200"
>
  Hover for details
</span>

Custom timing

<button
  amply-tooltip
  amply-tooltip-text="Delayed and slow"
  amply-tooltip-delay="500"
  amply-tooltip-duration="400"
>
  Slow reveal
</button>

JavaScript API

For advanced use cases, you can control tooltips programmatically:

import tooltip, {
  initTooltip,
  destroyTooltip,
  refreshTooltip,
  decodeHtmlEntities,
} from "@amplydevteam/tooltip";

// Re-initialize all tooltips (e.g., after dynamic content load)
tooltip.init();

// Initialize a specific element
initTooltip(document.querySelector("#my-button"));

// Destroy tooltip on element
destroyTooltip(document.querySelector("#my-button"));

// Refresh tooltip (re-read attributes)
refreshTooltip(document.querySelector("#my-button"));

// Destroy all tooltips
tooltip.destroyAllTooltips();

// Decode HTML entities (utility)
decodeHtmlEntities("&lt;b&gt;Bold&lt;/b&gt;"); // → "<b>Bold</b>"

Validation

Options are validated with Zod. Invalid values are logged to console with helpful error messages.

import {
  validateOptions,
  schemas,
} from "@amplydevteam/tooltip";

// Validate options programmatically
const result = validateOptions({
  text: "Hello",
  placement: "top",
  duration: 200,
});

if (result.success) {
  console.log(result.data);
} else {
  console.error(result.error);
}

// Access schemas for custom validation
const { PlacementSchema, AnimationSchema } = schemas;

Development

# Install dependencies
pnpm install

# Start dev server
pnpm dev

# Build for production
pnpm build

Release

# Create release (version bump + changelog + git tag)
pnpm run release

# Push with tags
git push --follow-tags origin main

# Publish to npm
pnpm publish

License

MIT