ActionHint

Updated: Sep 24, 2026

ActionHint is a short, non-interactive label that explains what an otherwise hard-to-discover action will do — “Preview item”, “Press to open”. It sits alongside the surface that owns the action; it never receives focus and never handles activation itself.

Use a few words and place the hint close to the surface it describes. The component owns a pill-shaped material background, an optional leading icon slot, padding, and text styling so the instruction stays legible over varied content.

ActionHint is built on StaticContainer, so it has no interaction states at all.

Usage

Place the hint next to the surface whose interaction it describes. It sizes itself, so give the row the layout and let the hint keep its intrinsic width:

import { ActionHint, Card, TextView } from '@wearables-ui-toolkit/mrbd';
import type { IconSource } from '@wearables-ui-toolkit/mrbd';

type PreviewCardProps = {
  caption: string;
  previewIcon: IconSource;
};

export function PreviewCard({ caption, previewIcon }: PreviewCardProps) {
  return (
    <Card>
      <TextView>{caption}</TextView>
      <div className="preview-card-footer">
        <ActionHint text="Preview item" icon={previewIcon} />
      </div>
    </Card>
  );
}

.preview-card-footer {
  display: flex;
  justify-content: flex-start;
  padding: var(--uit-spacing-medium);
}

The icon slot tints monochrome glyphs for you. When the artwork is full-color, pass an IconUriSource with tinting turned off:

import { ActionHint } from '@wearables-ui-toolkit/mrbd';

<ActionHint text="Open details" icon={{ uri: '/icons/details.png', tinted: false }} />;

Props

The full prop type is ActionHintProps. It extends StaticContainerProps minus children and material — the hint owns its material and takes its content through text and icon.

Own props

Prop	Type	Default	Description
`text`	`string`	`''`	The hint copy.
`icon`	`IconSource`	—	Optional leading icon.

Notable inherited props

Prop	Type	Default	Description
`shapeProvider`	`ShapeProvider`	rounded rectangle at the `xsmall` corner radius	Geometry used for clipping and every material path.
`width`	`number \\| string`	`'auto'`	Explicit width. Leave it unset so the hint sizes to its content.
`height`	`number \\| string`	`'auto'`	Explicit height. Leave it unset.
`backgroundStyle`	`BackgroundStyle`	`BackgroundStyle.PRIMARY`	Leave it at `PRIMARY` to keep the hint’s own material. `NONE` hides the material and leaves bare text; `SECONDARY` replaces the hint’s material with the secondary static material.
`visualState`	`VisualState`	`VisualState.DEFAULT`	Which material treatment the pill renders. Nothing changes it at runtime, because the hint has no interaction states. `backgroundStyle={BackgroundStyle.NONE}` forces `VisualState.NONE` regardless of this prop.
`useSmoothCorners`	`boolean`	`true`	Render smooth corners once the hint has been measured.
`clipContent`	`boolean`	`true`	Clip the content to the pill shape.
`className`	`string`	`''`	Extra class on the root element.
`contentClassName`	`string`	`''`	Extra class on the wrapper around the icon and text, between the material layers.
`style`	`CSSProperties`	`{}`	Extra inline styles. They merge over the hint’s own inline display and padding, so use them for placement, not for restyling.

Standard div attributes, including data-* and aria-* attributes, are forwarded to the root element, and a ref resolves to that element.

Behavior

The hint sizes itself to its content and carries its own horizontal and vertical padding.
The material is a two-layer pill: a diagonal light-to-transparent gradient with a soft glow stroke over it. It is static — there is no state transition to drive, because the hint is never interactive.
The copy uses the TextAppearance.META3 appearance in the primary text role, with additive blending so it lifts against whatever it sits over on the additive light display. The text does not wrap.
The icon slot uses the medium icon size and is tinted with the primary icon role, then separated from the copy by a small gap. Pass an icon source with tinting turned off if you need full-color artwork.
Omitting icon removes the slot entirely rather than leaving a gap; omitting text renders an empty label.
There are no focus, press, or disabled states: ActionHint is a label.

Accessibility

The hint’s text is ordinary visible content and is announced as such. It has no role and no focus stop, and its icon is decorative. Because it only describes an action, make sure the control or surface that actually performs the action carries its own accessible name — the hint is not a substitute. If the hint merely restates a label that a focusable element already announces, pass aria-hidden so it is not read twice.

Recommended patterns

Keep the copy to a few words that name the action so it is easy to scan.
Place the hint next to the surface whose action it explains.
Add an icon only when the glyph reinforces the instruction.
Let the hint size itself, and control its position from the surrounding layout.

Avoid

Handle activation on the accompanying surface rather than attaching a click handler to the hint. This keeps interaction semantics on the real control.
Use a button, badge, or status component when the content serves one of those roles; ActionHint remains a non-interactive label.
Remove the hint once the action is obvious, and avoid repeating an existing label.
Preserve the component-owned padding, text style, and intrinsic width so the pill remains consistent.
Keep copy to one line because ActionHint does not wrap long text.

Button, Tooltip, Tag, Chip, StaticContainer