Tooltips - Koala Design

How it works

The koala-tooltip tag helper sets data-tippy-content on the element. Tippy.js is loaded in the Portal layout and initialized with the koala theme. The tag helper itself lives in Koala.Web and works on any HTML element.

Tooltips are only initialised on devices with a real hover + fine pointer (@media (hover: hover) and (pointer: fine)). On touch devices a long-press / scroll can "stick" a tooltip across AJAX nav and obscure the next page, so the layout's tippy bootstrap skips initialisation entirely there. Don't rely on a tooltip to convey something a touch user must read — tooltips are progressive enhancement only.

// KoalaTooltipTagHelper.cs
[HtmlTargetElement(Attributes = "koala-tooltip")]
public class KoalaTooltipTagHelper : TagHelper
{
    [HtmlAttributeName("koala-tooltip")]
    public string? Tooltip { get; set; }

    public override void Process(TagHelperContext context, TagHelperOutput output)
    {
        output.Attributes.RemoveAll("koala-tooltip");

        if (string.IsNullOrWhiteSpace(Tooltip))
            return;

        output.Attributes.SetAttribute("data-tippy-content", Tooltip);
    }
}

Button tooltip

Add context to icon-only or abbreviated buttons.

<button koala-tooltip="Edit this quote" koala-btn="Primary">Edit</button>

<button koala-tooltip="Delete this item"
        koala-btn="Danger" koala-btn-variant="Outlined">Delete</button>

<button koala-tooltip="Copy to clipboard" class="p-2 ...">
    <!-- icon SVG -->
</button>

Avatar tooltip

Show the user's full name on hover. Useful for avatar stacks and compact lists.

SJ AG JW

<span koala-tooltip="Sarah Johnson"
      class="inline-flex items-center justify-center w-10 h-10 rounded-full ...">
    SJ
</span>

Badge tooltip

Provide extra context on status badges, such as dates or reasons.

Active Expiring Cancelled

<span koala-badge="Success" koala-tooltip="Active since January 2024">Active</span>

<span koala-badge="Warning" koala-tooltip="Expires on 15 April 2026">Expiring</span>

<span koala-badge="Danger"
      koala-tooltip="Cancelled by Sarah Johnson on 28 March 2026">Cancelled</span>

Portal initialization

Tippy.js is loaded via CDN in the Portal layout. Tooltips are initialized on page load and after Alpine-AJAX swaps using a MutationObserver-based init() function.

<!-- CDN scripts in _Layout.cshtml -->
<script src="https://unpkg.com/@popperjs/core@2"></script>
<script src="https://unpkg.com/tippy.js@6"></script>

<!-- Initialization -->
<script>
document.querySelectorAll('[data-tippy-content]').forEach(function (el) {
    if (!el._tippy) {
        tippy(el, {
            arrow: true,
            animation: 'shift-away',
            duration: [200, 0],
            theme: 'koala'
        });
    }
});
</script>

Koala theme CSS

The custom theme is defined in Assets/app.css and applies dark backgrounds with white text, matching the app's design language.

.tippy-box[data-theme~='koala'] {
    @apply bg-gray-900 dark:bg-gray-700 text-white text-sm rounded-lg font-medium;
}

.tippy-box[data-theme~='koala'] > .tippy-content {
    @apply px-3 py-1.5;
}

.tippy-box[data-theme~='koala'] > .tippy-arrow::before {
    border-top-color: var(--color-gray-900) !important;
}

:where(.dark) .tippy-box[data-theme~='koala'] > .tippy-arrow::before {
    border-top-color: var(--color-gray-700) !important;
}