On-canvas instruction or status pill with frosted, muted, and marquee variants.
Also known as: instruction chip, hint pill, canvas hint, marquee hint
Install with the CLI, or copy the component source into your project.
Add overlay-hint (npm)
1npx --yes -p @default-file/ui df-ui add overlay-hint
Frosted glass for tool canvases. Toggle the preview surface to switch between light and dark. Same recipe, inverted chrome.
Solid muted surface chip for light tool headers and stages (Color Lab, Design Extractor). Separate from frosted glass.
Pass children for a one-line hint. Prefer parts when you need a separator between segments.
Replace the middle dot with a glyph, icon, or custom divider. Use OVERLAY_HINT_SEPARATOR for the stock dot.
Optional leading and trailing slots for icons or custom nodes.
Leading and trailing work the same on the muted variant.
Tune corner radius, fill, border, label, shadow, and blur with props or --overlay-hint-* CSS variables.
Scrolling label with a trailing kit icon-only Button. Hover does not pause the loop. By default the whole chip is clickable (clickTarget chip). Docs demos toast on click instead of navigating away.
Pass scheme="dark" for the dark marquee recipe on dark canvases.
clickTarget chip makes the whole hint the hit target. action limits clicks to the trailing control only. Each demo toasts so you can tell which target fired.
size controls marquee density. sm is compact for marketing chrome; md is the default catalogue size.
marqueeWidth sets the visible scrolling viewport. Pass any CSS length; theme default is 12rem.
Three chip radii that read apart: none, md, and full. The trailing control stays a kit icon-only Button.
speed is the loop duration in seconds. Smaller values scroll faster.
Instruction or status pill for tool chrome. Default is frosted glass that follows light and dark surfaces. Muted is a solid chip. Marquee scrolls the label with an optional trailing icon action and sm or md density. Label ink is optically centered to cap height with text-box when available, and a 1cap line box otherwise. Chrome is tokenized via --overlay-hint-*.
| Prop | Type | Default | Notes |
|---|---|---|---|
| variant | "default" | "muted" | "marquee" | "default" | default frosted glass that adapts under a .dark surface. muted solid surface chip. marquee scrolling label with an optional trailing icon action. |
| scheme | "light" | "dark" | - | Explicit light or dark recipe for marquee. When omitted, marquee follows a .dark ancestor like default. |
| speed | number | 18 | Marquee loop duration in seconds. Smaller values scroll faster. Sets --overlay-hint-marquee-duration. |
| marqueeWidth | string | - | Visible marquee viewport width. Any CSS length such as 10rem or 14rem. Theme default is 12rem. Sets --overlay-hint-marquee-width. |
| clickTarget | "chip" | "action" | "chip" | Marquee hit target. chip makes the whole hint clickable; the trailing icon is decorative. action limits clicks to the trailing control only. |
| size | "sm" | "md" | "md" | Marquee density only. md is the default chip. sm tightens padding, uses text-11 type, and shrinks the trailing control for compact tool chrome. Ignored on default and muted. |
| action | ReactNode | - | Icon for the trailing marquee control. Renders as a kit icon-only Button (size icon-xs, variant secondary). Decorative when clickTarget is chip. Interactive when clickTarget is action. |
| actionLabel | string | - | Accessible name for the interactive control (whole chip or trailing action). |
| onAction | MouseEventHandler<HTMLElement> | - | Click handler when the interactive control renders as a button. |
| actionHref | string | - | When set, the interactive control renders as a link instead of a button. |
| radius | "none" | "md" | "full" | "md" | Corner radius for the hint chip: none square, md soft, full pill. Three steps kept distinct. Trailing marquee control uses the Button radius. Maps to --overlay-hint-radius. |
| cornerShape | "round" | "smooth" | - | Instance corner curve. Omit to inherit --df-corner-shape from the theme (set at create/init). |
| background | string | - | Background color. Prefer tokens such as var(--df-neutral-900). Sets --overlay-hint-bg. |
| borderColor | string | - | Border color. Prefer tokens such as var(--border). Sets --overlay-hint-border. |
| foreground | string | - | Label color. Prefer tokens such as var(--muted-foreground). Sets --overlay-hint-fg. |
| shadow | string | - | Box shadow. Prefer tokens such as var(--overlay-shadow) or none. Sets --overlay-hint-shadow. |
| blur | string | - | Backdrop blur length. Prefer tokens such as var(--overlay-blur) or 0px. Sets --overlay-hint-blur. |
| parts | ReactNode[] | - | Label segments joined by separator. Prefer this for multi part hints. When set, children is ignored. |
| separator | ReactNode | OVERLAY_HINT_SEPARATOR (·) | Node between parts. Defaults to the middle dot constant. Pass a glyph, icon, or custom divider. Set null to omit. |
| children | ReactNode | - | Single label hint. Use parts instead when you need a separator between segments. |
| leading | ReactNode | - | Optional icon, swatch, or node before the label. |
| trailing | ReactNode | - | Optional icon or node after the label. |
| className | string | - | Additional styles. On dark canvases without a .dark ancestor, pass className="dark" so default frosted uses the dark recipe. |
| style | CSSProperties | - | Inline styles. Override --overlay-hint-bg, --overlay-hint-border, --overlay-hint-fg, --overlay-hint-shadow, --overlay-hint-blur, or --overlay-hint-radius directly. |
Named exports from the Overlay Hint module: OverlayHint component; OVERLAY_HINT_SEPARATOR middle-dot constant; OverlayHintSize (sm | md); OverlayHintClickTarget (chip | action).
Theme defaults live on :root. Override these globally or set the instance vars via props or style.
| Token | Type | Default | Notes |
|---|---|---|---|
| --overlay-hint-radius | CSS length | var(--radius-md) | Corner radius used by the hint. |
| --df-corner-shape | CSS corner-shape | var(--df-corner-shape-round) | Theme corner curve for all kit chrome. round = circular arcs; smooth = continuous squircle. Set with df-ui init --corner-shape, or override on :root. Default round. |
| --df-label-line-height | CSS line-height | var(--df-leading-none) | Line box for label flex centering. Defaults to --df-leading-none. When text-box is unavailable and the cap unit is supported, the kit sets this to 1cap so flex centering matches cap-height ink. |
| --overlay-hint-bg | CSS color | - | Resolved fill for the active surface. |
| --overlay-hint-border | CSS color | - | Resolved border color. |
| --overlay-hint-fg | CSS color | - | Resolved label color. |
| --overlay-hint-shadow | CSS shadow | - | Resolved box shadow. |
| --overlay-hint-blur | CSS length | - | Resolved backdrop blur. |
| --overlay-hint-default-bg | CSS color | color-mix(in oklch, white 78%, transparent) | Default frosted fill on light surfaces. |
| --overlay-hint-default-border | CSS color | color-mix(in oklch, black 10%, transparent) | Default frosted border on light surfaces. |
| --overlay-hint-default-fg | CSS color | color-mix(in oklch, black 72%, transparent) | Default frosted label on light surfaces. |
| --overlay-hint-default-shadow | CSS shadow | 0 10px 28px color-mix(in oklch, black var(--df-shadow-intensity-md), transparent) | Default frosted shadow on light surfaces. |
| --overlay-hint-default-blur | CSS length | var(--overlay-blur) | Default frosted blur on light surfaces. |
| --overlay-hint-default-dark-bg | CSS color | var(--overlay-bg) | Default frosted fill on .dark surfaces. |
| --overlay-hint-default-dark-border | CSS color | var(--overlay-border) | Default frosted border on .dark surfaces. |
| --overlay-hint-default-dark-fg | CSS color | var(--overlay-item-fg) | Default frosted label on .dark surfaces. |
| --overlay-hint-default-dark-shadow | CSS shadow | var(--overlay-shadow) | Default frosted shadow on .dark surfaces. |
| --overlay-hint-default-dark-blur | CSS length | var(--overlay-blur) | Default frosted blur on .dark surfaces. |
| --overlay-hint-muted-bg | CSS color | var(--muted) | Muted variant fill. |
| --overlay-hint-muted-border | CSS color | var(--border) | Muted variant border. |
| --overlay-hint-muted-fg | CSS color | var(--muted-foreground) | Muted variant label. |
| --overlay-hint-muted-shadow | CSS shadow | none | Muted variant shadow. |
| --overlay-hint-muted-blur | CSS length | 0px | Muted variant blur. |
| --overlay-hint-marquee-duration | CSS time | 18s | One full marquee loop duration. |
| --overlay-hint-marquee-width | CSS length | 12rem | Visible marquee viewport width. |
| --overlay-hint-marquee-bg | CSS color | color-mix(in oklch, white 88%, transparent) | Marquee fill on light surfaces. |
| --overlay-hint-marquee-dark-bg | CSS color | var(--overlay-bg) | Marquee fill on dark surfaces. |
| --overlay-hint-marquee-gap | CSS length | calc(4 * var(--spacing-unit)) | Gap between repeated marquee label segments. |
| --overlay-hint-marquee-fade | CSS length | 0.75rem | Soft edge fade depth for the scrolling label, on both sides. |