FlexTip Documentation


Markup

A FlexTip can be created declaratively by adding the flextip class to a <div>. Use data-attributes to configure that particular FlexTip.

The content inside the <div> becomes the tooltip content. When data-target-id is omitted, FlexTip creates an information icon at the position where the FlexTip markup was declared.

An existing button can be used as the target. Set its type explicitly when it is not intended to submit a form.

This example only specifies a target. All other values use the defaults shown on the Default configuration tab.

<button id="productHelp" type="button">Product help</button>

<div class="flextip"
    data-target-id="productHelp">
    Product information
</div>

An existing target can be annotated after its text. superscript adds a raised information “i”, while superscript-question adds a raised question mark. Both annotations work in ordinary inline layouts and when the annotation is a flex item.

<span id="commissionRateHelp">Commission rate</span>
<div class="flextip"
    data-target-id="commissionRateHelp"
    data-target-annotation-style="superscript-question">
    The commission rate as a percentage
</div>

<span id="productInfo">Product</span>
<div class="flextip"
    data-target-id="productInfo"
    data-target-annotation-style="superscript">
    Product information
</div>

A FlexTip can also be created programmatically. A content callback is evaluated immediately before every opening and receives the current target and FlexTip instance. It can therefore return fresh target-specific content without recreating or manually updating the FlexTip.

const targets = document.querySelectorAll(".product-help");

function createContent(target) {
    const fragment = document.createDocumentFragment();
    const text = document.createElement("span");
    text.textContent = target.dataset.tipContent;
    fragment.appendChild(text);
    return fragment;
}

const productTip = FlexTip.create({
    target: {
        element: targets[0]
    }
}, createContent);

targets.forEach(target => {
    target.addEventListener("mouseenter", () => {
        productTip.update({
            target: {
                element: target
            }
        }).showTip();
    });
});
Default configuration

Use FlexTip.configure(<options object>) to change the defaults for all FlexTips created afterwards on the page.

FlexTip.configure({
    trigger: "hover",
    autoClose: true,
    closeOnEscape: true,
    position: "top",
    align: "center",
    gap: "5px",
    zIndex: 1000,
    target: {
        annotationStyle: "none",
        iconColor: "#ccc"
    },
    arrow: {
        use: true,
        size: "5px"
    },
    styles: {
        cssClass: "",
        padding: "5px 10px",
        backgroundColor: "#f6f6f6",
        borderRadius: "4px",
        transition: "opacity 0.5s",
        boxShadow: "0 2px 8px rgba(0, 0, 0, 0.15)"
    },
    scrim: {
        opacity: 0,
        backgroundColor: "transparent"
    }
});
Data-attributes

Data-attributes configure an individual declarative FlexTip and override the corresponding default configuration.

Attribute Values Description
class flextip
  • Mandatory.
  • Transforms the <div> into a FlexTip.
id Unique HTML id
  • Optional.
  • No default.
  • Identifies the tooltip element when direct DOM access is needed.
data-trigger hover | click
  • Optional.
  • Default: hover.
  • hover shows the tip when the pointer enters the target and hides it shortly after the pointer leaves the target and tip.
  • click toggles the tip when the target is clicked and enables the shared scrim.
data-auto-close true | false
  • Optional.
  • Default: true.
  • When true, clicking inside the tooltip closes it.
data-close-on-escape true | false
  • Optional.
  • Default: true.
  • When true, pressing Escape while the tooltip is open closes it.
data-position top | right | bottom | left
  • Optional.
  • Default: top.
  • Sets the preferred side of the target.
  • FlexTip can choose another side when the preferred side does not have enough room.
  • The final tooltip position is constrained to the viewport.
data-align start | center | end
  • Optional.
  • Default: center.
  • Aligns the tooltip along the target on its selected side.
data-gap Pixel length
  • Optional.
  • Default: 5px.
  • Sets the distance between the target and tooltip before the arrow size is added.
data-z-index Number
  • Optional.
  • Default: 1000.
  • Sets the tooltip z-index. For click-triggered tips, the scrim is placed one level below it.
target Options for the element that triggers and anchors the tooltip.
data-target-id HTML id
  • Optional.
  • No default.
  • Identifies the existing page element that triggers and anchors the tooltip.
  • Supported targets: IMG, SPAN, LABEL, DIV, A, and BUTTON.
  • When omitted, FlexTip creates an information icon next to the declarative FlexTip markup.
data-target-annotation-style none | underline | superscript | superscript-question | bracketed
  • Optional.
  • Default: none.
  • underline adds a dotted underline to the target.
  • superscript adds a raised blue “i” annotation after the target.
  • superscript-question adds a raised “?” annotation after the target.
  • Both superscript annotations support ordinary inline and flex layouts.
  • bracketed adds a “[?]” annotation after the target.
data-target-icon-color CSS color
  • Optional.
  • Default: #ccc.
  • Sets the color of the generated information icon when data-target-id is omitted.
arrow Options for the arrow between the tooltip and target. Short tooltips keep visible overflow so the arrow does not create a scrollbar. Vertical scrolling is enabled only when tooltip content exceeds the available viewport height.
data-arrow-use true | false
  • Optional.
  • Default: true.
  • Controls whether the tooltip has an arrow.
data-arrow-size Pixel length
  • Optional.
  • Default: 5px.
  • Sets the arrow border size and contributes to the distance between tooltip and target.
styles Visual options applied directly to the tooltip element.
data-styles-css-class CSS class name
  • Optional.
  • Default: an empty string.
  • Adds a custom CSS class to the tooltip.
data-styles-padding CSS padding
  • Optional.
  • Default: 5px 10px.
data-styles-background-color CSS color | none
  • Optional.
  • Default: #f6f6f6.
  • Accepts any valid CSS color.
  • none keeps a background supplied by other CSS; FlexTip reads the computed color for the arrow.
data-styles-border-radius CSS border-radius
  • Optional.
  • Default: 4px.
data-styles-transition CSS transition
  • Optional.
  • Default: opacity 0.5s.
data-styles-box-shadow CSS box-shadow
  • Optional.
  • Default: 0 2px 8px rgba(0, 0, 0, 0.15).
scrim Options for the shared page scrim used by click-triggered FlexTips.
data-scrim-opacity Number from 0 to 1
  • Optional.
  • Default: 0.
  • Sets the visible scrim opacity while a click-triggered FlexTip is open.
data-scrim-background-color CSS color
  • Optional.
  • Default: transparent.
  • The value is read into the individual FlexTip configuration, but the current shared scrim takes its background color from the global default when initialized.
  • Use FlexTip.configure({ scrim: { backgroundColor: "..." } }) before initialization to change the shared scrim background.
Events
This UX component does not have any events.
API
Method Parameters and return value Description
FlexTip.configure(options)
  • options: partial configuration object.
  • Returns nothing.
 Deep-merges options into the defaults used by FlexTips created afterwards.
FlexTip.create(options, content)
  • options: configuration object. Use target.id or target.element to select an existing target.
  • content: optional string, Element, DocumentFragment, or a callback returning one of those types. The callback receives the current target and FlexTip instance.
  • Returns the new FlexTip instance when created immediately. An id-based request made before initialization is queued and returns null.
 Creates a programmatic FlexTip. String content is inserted as HTML. An Element or DocumentFragment is moved into the tooltip. A content callback is evaluated immediately before every opening.
FlexTip.closeAll() Returns nothing. Hides every FlexTip instance registered on the page.
myFlexTip.update(options, content)
  • options: optional partial configuration object.
  • content: optional supported content value.
  • Returns the same FlexTip instance for chaining.
 Hides the tip, detaches it from its previous target, applies the supplied configuration, attaches it to the new target, and optionally replaces its content. Use target.element to reuse one instance across multiple page elements. Changing trigger immediately rebinds the interaction listeners on both the target and tooltip.
myFlexTip.updateContent(content)
  • content: string, Element, DocumentFragment, or a callback returning one of those types. The callback receives the current target and FlexTip instance.
  • Returns the same FlexTip instance for chaining.
 Replaces only the user-provided tooltip content while preserving the arrow and hover bridge. A callback remains registered and is evaluated immediately before every opening.
myFlexTip.showTip() Returns nothing. Positions and shows the tooltip for its current target.
myFlexTip.hideTip() Returns nothing. Hides the tooltip and removes its open state from the current target.