HelpTooltip

Installation

1. Install the package.

npm install @hashintel/ds-components

2. Import the component.

import { HelpTooltip } from "@hashintel/ds-components";

export const EntityTypeLabel = () => (
  <span>
    Entity type
    <HelpTooltip content="The schema this entity conforms to" />
  </span>
);

When to use

When not to use

Examples

Basic

Place it flush after the term it explains, with the explanation in content. Don't type a space before it — the icon brings its own gap and stays glued to the last word.

Alignment

align tunes the icon's vertical position: top (default) suits labels and running text; use center in vertically centered rows such as tab labels.

Tooltip position

The tooltip prefers the right side, where it won't cover the text just read, and flips automatically when there's no room. Set position to prefer another side.

Light and dark

variant sets the overlay surface. Keep the default dark for contrast; switch to light where a dark panel feels heavy against the surrounding UI.

In form labels

In forms, don't place HelpTooltip by hand: Form.Field takes labelTooltip and renders the icon after the label text — outside the <label> element and on the side away from the control.

import { useState } from "react";

import { Form, TextInput } from "@hashintel/ds-components";

export const WorkspaceNameField = () => {
  const [name, setName] = useState("");
  return (
    <Form.Field
      label="Workspace name"
      labelTooltip="Shown in the sidebar and on invitations"
    >
      <TextInput value={name} onChange={setName} placeholder="Acme Research" />
    </Form.Field>
  );
};

Content

• Write one clarifying sentence, ideally under 15 words — the overlay caps at its width and wraps; anything needing paragraphs belongs in a Popover or the docs.
• Add what the label can't carry: a definition, a consequence, a constraint, or a default. Don't restate the label — a redundant tooltip teaches users to skip the rest.
• Keep it plain text in sentence case. No links or "Learn more" — they're unreachable in a hover overlay.

Accessibility

HelpTooltip implements the WAI-ARIA tooltip pattern.

What HelpTooltip provides

• The icon trigger receives tabindex="0" automatically, so keyboard users can reach it; the tooltip opens on hover and keyboard focus, and closes on Escape, blur, or pointer-leave.
• While open, the trigger references the content via aria-describedby, so screen readers announce the explanation.
• The trigger is exposed as an image named "Information" (role="img"), so it isn't an unnamed tab stop; the decorative info icon inside stays aria-hidden. Pass aria-label to rename it — useful when several help icons land in the same list of form fields.

What you must do

• Write the component flush against the preceding word, no space or line break before it, to avoid the help tooltip becoming a widow.
• Keep content plain text so the aria-describedby announcement reads cleanly.
• Place the trigger beside, not inside, <label> elements — inside one, clicking the icon focuses the form control. Form.Field already renders it outside.

API reference