Reusable Tooltip Directive Documentation

1. Introduction

The reusableTooltip directive in Angular provides a versatile way to add tooltips to elements with extensive customization options for content, appearance, and behavior.

2. Usage

Apply the reusableTooltip directive to HTML elements and bind the tooltip content and configuration.

1. Using a String

For simple text content, you can use a string directly with the tooltip attribute.

<a [tooltip]="'This is a tooltip text'"
   [options]="TOOLTIP_CONFIG"
   reusableTooltip>
  Hover over me
</a>

In this example, 'This is a tooltip text' will be displayed as the tooltip content.

2. Using HTML

If you need to include HTML content in your tooltip, set contentType to 'html' and provide HTML content as a string.

<a [tooltip]="'<strong>Bold Text</strong> with <a href=\"<https://example.com\>">link</a>'"
   [options]="{ contentType: 'html', ...TOOLTIP_CONFIG }"
   reusableTooltip>
  Hover over me
</a>

In this example, the tooltip will display HTML content, including bold text and a link.

3. Using an Angular Template

For more complex content, you can use an Angular template. First, define the template in your component's HTML file.

Template Definition (in component HTML):

<ng-template #tooltipTemplate>
  <div>
    <h4>Tooltip Title</h4>
    <p>Detailed content goes here.</p>
  </div>
</ng-template>

Then, reference this template in the tooltip attribute of the directive.

<a [tooltip]="tooltipTemplate"
   [options]="{ contentType: 'template', ...TOOLTIP_CONFIG }"
   reusableTooltip>
  Hover over me
</a>

In this example:

#tooltipTemplate is a reference to the Angular template defined in the same component.
The tooltip attribute uses this template, and contentType is set to 'template'.

Summary

String Content: Use for simple text.
HTML Content: Use for rich text with HTML.
Angular Template: Use for complex content involving Angular components or directives.

3. Configuration Options

The tooltip can be customized using the following options:

Light Theme Tooltip View:

Dark Theme Tooltip View:

TooltipOptions Interface:

export interface TooltipOptions {
  placement?: string;                   // Position of the tooltip ('top', 'bottom', 'left', 'right')
  autoPlacement?: boolean;              // Automatically adjust tooltip placement
  contentType?: 'string' | 'html' | 'template'; // Type of content to display
  showDelay?: number;                   // Delay before showing the tooltip (ms)
  hideDelay?: number;                   // Delay before hiding the tooltip (ms)
  hideDelayMobile?: number;             // Delay before hiding the tooltip on mobile (ms)
  hideDelayTouchscreen?: number;        // Delay before hiding the tooltip on touchscreen devices (ms)
  zIndex?: number;                      // z-index of the tooltip
  animationDuration?: number;           // Duration of the animation (ms)
  animationDurationDefault?: number;    // Default animation duration (ms)
  trigger?: string;                     // Trigger to show the tooltip ('hover', 'click', etc.)
  tooltipClass?: string;                // Additional CSS class for styling
  display?: boolean;                    // Display the tooltip
  displayMobile?: boolean;              // Display tooltip on mobile devices
  displayTouchscreen?: boolean;         // Display tooltip on touchscreen devices
  shadow?: boolean;                     // Show shadow around the tooltip
  theme?: 'dark' | 'light';             // Theme for the tooltip ('dark', 'light', etc.)
  offset?: number;                      // Offset for positioning (px)
  width?: number;                       // Tooltip width (px)
  maxWidth?: number;                    // Maximum width for the tooltip (px)
  id?: string | number;                 // Identifier for the tooltip instance
  hideDelayAfterClick?: number;         // Delay to hide the tooltip after a click (ms)
  pointerEvents?: 'auto' | 'none';      // CSS pointer-events property
  position?: { top: number; left: number; }; // Custom position for the tooltip
}

Default Options/Configuration: No configuration required for generic use cases. See below default option for more.

export const defaultOptions: TooltipOptions = {
  placement: 'bottom',
  autoPlacement: true,
  contentType: 'string',
  showDelay: 0, // No delay, Show immediately on hover
  hideDelay: 0, // No delay, Hide immediately on hover
  hideDelayMobile: 0,
  hideDelayTouchscreen: 0,
  zIndex: 0,
  animationDuration: 300,
  animationDurationDefault: 300,
  trigger: 'hover',
  tooltipClass: '',
  display: true,
  displayMobile: true,
  displayTouchscreen: true,
  shadow: true,
  theme: 'dark',
  offset: 8,
  maxWidth: 300,
  id: 1,
  hideDelayAfterClick: 2000,
  pointerEvents: 'auto'
};

Main Options:

placement: Defines the position of the tooltip relative to the target element. Possible values include top, bottom, left, right.
autoPlacement: If true, the tooltip will automatically adjust its position if the specified placement results in it being cut off or going outside the viewport.
contentType: Specifies the type of content displayed inside the tooltip. Options are string (plain text), html (HTML content), and template (Angular template).
showDelay: Time in milliseconds to wait before showing the tooltip after the trigger event.
hideDelay: Time in milliseconds to wait before hiding the tooltip after the trigger event ends.
hideDelayMobile: Time in milliseconds to wait before hiding the tooltip on mobile devices.
hideDelayTouchscreen: Time in milliseconds to wait before hiding the tooltip on touchscreen devices.
zIndex: CSS z-index property to control the stacking order of the tooltip.
animationDuration: Duration of the tooltip animation in milliseconds.
animationDurationDefault: Default duration for tooltip animations if no specific duration is provided.
trigger: Event that triggers the tooltip display. Possible values include hover, click.
tooltipClass: Additional CSS class for custom styling of the tooltip.
display: Boolean to control whether the tooltip is displayed.
displayMobile: Boolean to control whether the tooltip is displayed on mobile devices.
displayTouchscreen: Boolean to control whether the tooltip is displayed on touchscreen devices.
shadow: Boolean to enable or disable shadow around the tooltip.
theme: Theme for the tooltip. Options include dark and light.
offset: Offset in pixels for positioning the tooltip away from the target element.
width: Fixed width of the tooltip in pixels.
maxWidth: Maximum width of the tooltip in pixels.
id: Identifier for the tooltip instance, which can be useful for managing multiple tooltips.
hideDelayAfterClick: Delay in milliseconds before hiding the tooltip after a click event.
pointerEvents: CSS property to control pointer events (auto or none).
position: Custom position object with top and left properties for precise placement.

6. How It Works

Initialization: The reusableTooltip directive sets up the tooltip based on provided options.
Triggering: Tooltips are displayed based on the trigger event (e.g., hover, click).
Positioning: Tooltips are positioned relative to the target element, with options for automatic adjustments.
Content Handling: Supports various content types, including strings, HTML, or Angular templates.
Animation: Tooltips animate in and out based on the specified animation duration.

7. Additional Notes

Mobile and Touchscreen Display: Use displayMobile and displayTouchscreen to manage tooltip visibility on different devices, ensuring an optimal user experience.
Backward Compatibility: Handle any deprecated or renamed options as needed.

8. Conclusion

The reusableTooltip directive offers comprehensive customization for tooltips in Angular applications, allowing you to tailor the tooltip’s appearance and behavior to meet specific needs and enhance user experience.

Software Development