Skip to content
GitHub
API reference

Bar tooltips

Enable the built-in hover tooltip or compose a custom popup.

Usage

import { GanttBarTooltip, type GanttBarsSlots } from "@art-tools/react-gantt";

const bars: GanttBarsSlots = {
  tooltip: { slots: { tooltip: GanttBarTooltip } },
};

// <Gantt tasks={tasks} bars={bars} />
  • The tooltip slot is empty by default and bars retain their native title. Assign GanttBarTooltip to bars.tooltip.slots.tooltip to enable the built-in popup.
  • Custom tooltip roots receive the task, derived progress, inclusive displayEnd, and an anchor ref. BarTooltipRoot, BarTooltipTrigger, and useBarTooltip expose the shared hover state for custom compositions.
  • Replacing a bar's root replaces the default DraggableBar wrapper, which owns tooltip mounting. A custom bar root must preserve the behavior it needs.

The built-in bar tooltip. Opt in with `slots={{ tooltip: GanttBarTooltip }}`; it is never rendered by default. A wrapper, not a sibling: it renders the bar it is handed and mounts its own root and trigger around it, so it holds no privileged position over any other slot (ADR-022). Placed from the cursor in JS, not with CSS anchor positioning: anchoring to the bar puts the tooltip at the midpoint of a bar that can be wider than the viewport. It follows the pointer for as long as it is open; there is no dwell delay.

/**
 * The built-in bar tooltip. Opt in with `slots={{ tooltip: GanttBarTooltip }}`;
 * it is never rendered by default.
 *
 * A wrapper, not a sibling: it renders the bar it is handed and mounts its own
 * root and trigger around it, so it holds no privileged position over any other
 * slot (ADR-022).
 *
 * Placed from the cursor in JS, not with CSS anchor positioning: anchoring to the
 * bar puts the tooltip at the midpoint of a bar that can be wider than the
 * viewport. It follows the pointer for as long as it is open; there is no dwell
 * delay.
 */
export declare function GanttBarTooltip(props: BarTooltipProps & ComponentProps<"div">): JSX.Element;

Owns one bar tooltip's open state and publishes it to `BarTooltipTrigger` and whatever renders the popup. Belongs *inside* the tooltip slot, and a slot is free to skip it entirely and use a third-party tooltip's root instead (ADR-022). Exported for the middle case: a custom tooltip that wants the library's hover and closing behaviour with different markup. Compose it with `BarTooltipTrigger` and `useBarTooltip`.

/**
 * Owns one bar tooltip's open state and publishes it to `BarTooltipTrigger` and
 * whatever renders the popup.
 *
 * Belongs *inside* the tooltip slot, and a slot is free to skip it entirely and
 * use a third-party tooltip's root instead (ADR-022).
 *
 * Exported for the middle case: a custom tooltip that wants the library's hover
 * and closing behaviour with different markup. Compose it with
 * `BarTooltipTrigger` and `useBarTooltip`.
 */
export declare function BarTooltipRoot(props: {
    anchorRef: RefObject<HTMLDivElement | null>;
    children: ReactNode;
}): JSX.Element;

Turns the element it is given into the tooltip's trigger. Belongs inside the tooltip slot, under a `BarTooltipRoot` and wrapped around the slot's `children`: that is what makes hover behaviour the slot's own business rather than the bar's. It **merges** onto that element rather than wrapping it, which is not a style preference: the bar contains `<button>` resize and connector handles, so a wrapping trigger — Base UI's default renders a `<button>` — would nest buttons and produce invalid HTML that breaks those controls. `cloneElement` adds no DOM at all. Handlers are composed with whatever the element already has, so a consumer's `slotProps.root` handlers and the a11y payload keep firing.

/**
 * Turns the element it is given into the tooltip's trigger. Belongs inside the
 * tooltip slot, under a `BarTooltipRoot` and wrapped around the slot's
 * `children`: that is what makes hover behaviour the slot's own business rather
 * than the bar's.
 *
 * It **merges** onto that element rather than wrapping it, which is not a style
 * preference: the bar contains `<button>` resize and connector handles, so a
 * wrapping trigger — Base UI's default renders a `<button>` — would nest buttons
 * and produce invalid HTML that breaks those controls. `cloneElement` adds no DOM
 * at all.
 *
 * Handlers are composed with whatever the element already has, so a consumer's
 * `slotProps.root` handlers and the a11y payload keep firing.
 */
export declare function BarTooltipTrigger(props: {
    children: ReactNode;
}): ReactNode;

The enclosing `BarTooltipRoot`'s state, or `null` when there is none.

/** The enclosing `BarTooltipRoot`'s state, or `null` when there is none. */
export declare const useBarTooltip: () => BarTooltipContextValue | null;
BarTooltipProps documented properties
PropertyType & description
taskRequiredGanttTask
progressRequirednumber

Resolved progress, override-aware during a drag — not `task.progress`.

displayEndRequiredDate | undefined

Inclusive, user-facing end date. `undefined` for an instant (a milestone).

childrenOptionalReactNode

The bar itself. The slot is a *wrapper*: it has to render this, and has to decide for itself when to show a popup beside it — there is no `open` prop, because the chart holds no open state (ADR-022). Use `BarTooltipRoot` + `BarTooltipTrigger` for the built-in hover behaviour, or a third-party tooltip's own root and trigger.

anchorRefRequiredRefObject<HTMLDivElement | null>

The bar's DOM node, for a custom tooltip that wants to position against the bar rather than the cursor. `null` until the bar mounts, and also when a consumer has replaced `slots.root` with a component that does not forward refs. The built-in tooltip ignores it — it places from the cursor (ADR-022).

TypeScript declaration
export declare interface BarTooltipProps extends BarTooltipOwnerState {
    /**
     * The bar's DOM node, for a custom tooltip that wants to position against the
     * bar rather than the cursor. `null` until the bar mounts, and also when a
     * consumer has replaced `slots.root` with a component that does not forward
     * refs.
     *
     * The built-in tooltip ignores it — it places from the cursor (ADR-022).
     */
    anchorRef: RefObject<HTMLDivElement | null>;
}

Open state shared *within one tooltip slot*, owned by `BarTooltipRoot` and read by `BarTooltipTrigger` and the popup. It sits inside the slot rather than in `BarTooltipConsumer` so that nothing outside the slot has an opinion about open state (ADR-022). `null` means there is no root above, which is why `BarTooltipTrigger` is a no-op rather than an error: `TaskBar`/`ProjectBar`/`MilestoneBar` are public exports that render standalone.

BarTooltipContextValue documented properties
PropertyType & description
openRequiredboolean
setOpenRequired(open: boolean) => void
anchorRefRequiredRefObject<HTMLDivElement | null>

The bar's DOM node, used to verify the pointer really did leave it.

TypeScript declaration
/**
 * Open state shared *within one tooltip slot*, owned by `BarTooltipRoot` and read
 * by `BarTooltipTrigger` and the popup.
 *
 * It sits inside the slot rather than in `BarTooltipConsumer` so that nothing
 * outside the slot has an opinion about open state (ADR-022).
 *
 * `null` means there is no root above, which is why `BarTooltipTrigger` is a
 * no-op rather than an error: `TaskBar`/`ProjectBar`/`MilestoneBar` are public
 * exports that render standalone.
 */
export declare interface BarTooltipContextValue {
    open: boolean;
    setOpen: (open: boolean) => void;
    /** The bar's DOM node, used to verify the pointer really did leave it. */
    anchorRef: RefObject<HTMLDivElement | null>;
}

Related examples