Coachmark

Installation

pnpm dlx shadcn@latest add https://matos-ui.com/r/coachmark.json

Usage

import { Coachmark, type CoachmarkStep } from '@/components/matos-ui/coachmark'

const steps: CoachmarkStep[] = [
  { target: '#new-button', title: 'Start here', description: 'Create anything from one place.' },
  { target: '#search', title: 'Jump anywhere', description: 'Also ⌘K from any screen.' },
]

const [open, setOpen] = useState(false)

<button onClick={() => setOpen(true)}>Take the tour</button>
<Coachmark steps={steps} open={open} onOpenChange={setOpen} />

A target is a CSS selector, an Element, a ref, or a function returning one.

Three tiers, on purpose

Three things move the moment a step opens, and none of them can share timing:

spring.gentle on the card would drift; spring.moderate on the scrim would snap; a looping glow would nag. This component is the one place all three are on screen together, and the contrast is the argument.

How it's built

• The scrim is a box-shadow. A cutout element the size of the target casts a 100vmax shadow — that shadow is the dimming. Moving it (x / y / width / height) on gentle glides the spotlight; a flat click-catcher behind it blocks the page.
• The card is Elevated offset={4}, portaled to document.body with the substrate reset to the page (like Achievement Toast), so that rung means the same wherever the tour runs. It flips above the target when there's no room below.
• The ring fires attentionGlow once when rect first resolves for a step — never on the re-measure poll that follows the target into view.
• prefers-reduced-motion drops the glide, the card slide and the glow; scrolling to the target is instant, and the scrim and card still fade.

Reference

Coachmark Props

CoachmarkStep