ContextualHelp

Displays contextual help via popover on button click

The <ContextualHelp> component provides inline assistance to help users understand specific parts of your interface. It displays a small button with an icon that, when clicked, opens a popover with explanatory content. This content can be rich and interactive, unlike tooltips which are intended for brief, passive messages.

Use <ContextualHelp> when users might need deeper guidance or context, especially for complex settings, form inputs, or unfamiliar actions.

Anatomy

Anatomy of tooltip
  • Trigger button: A small icon button that activates the help popover.
  • Popover: A floating container for detailed help content.
  • Dialog content: Custom content area that may contain headings, paragraphs, or even interactive elements.

Appearance

The appearance of a component can be customized using the variant and size props. These props adjust the visual style and dimensions of the component, available values are based on the active theme.

Variant
Size
The selected theme does not has any options for "variant".

Usage

ContextualHelp is ideal when brief tooltips are insufficient and users might benefit from more elaborate information. Avoid overusing it—too many help popovers can clutter the UI. Use tooltips for short, simple hints (e.g., labeling an icon), and reserve ContextualHelp for situations where users need deeper guidance or clarification. Aim to use it selectively on parts of your app where extra support truly adds value.

Do
Use contextual help for fields that users frequently misunderstand.

Use contextual help for fields that users frequently misunderstand.

Don't
Don't use contextual help for obvious or self-explanatory features.

Don't use contextual help for obvious or self-explanatory features.

Custom placement

The position of the popover can be customized using the placement prop. Available options include top, bottom, left, right, and aligned variants like bottom start.

Interactive content

Unlike tooltips, ContextualHelp supports complex and interactive content inside the popover—such as links, buttons, or structured text.

Props

Did you know? You can explore, test, and customize props live in Marigold's storybook. Watch the effects they have in real-time!
children
ReactNode;
Content rendered inside the popover.
defaultOpen?
boolean;
Whether the popover is open by default (uncontrolled).
offset?
number;
Offset (in px) between button and popover.
onOpenChange?
(isOpen: boolean) => void;
Handler that is called when the open state changes.
open?
boolean;
Controls the open state of the popover (controlled).
placement?
Placement;
Placement of the popover relative to the button.
ref?
Ref<HTMLInputElement>;
Allows getting a ref to the component instance. Once the component unmounts, React will set ref.current to null (or call the ref with null if you passed a callback ref). @see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}
width?
WidthProp;
Optional width size for the popover
Last update: a month ago