Skip to content

Coachmark

Coachmark points at an element to introduce it. It dims everything else, cuts a hole around the element, rings it with a pulse and shows a card with some text and a button.

Usage

Call Components.Coachmark with a scope and a table of properties:

local open = scope:Value(true)

C.Coachmark(scope, {
    Layer = overlayLayer,
    Target = newButton,
    Open = open,
    Step = "1 of 3",
    Title = "Try this first",
    Text = "The new button starts a project.",
    OnDismiss = function()
        open:set(false)
    end,
})

Scrim

The scrim is four rectangles around the element, not one dimmed layer, so the element stays visible and can still be pressed.

Position

The card and the pulse are placed in the space of the layer and kept inside it, so inside a Window the card stays in the window.

Properties

Name Type Required Default Description
Theme ThemeRef ❌ The contextual theme Theme to use for this component instead of the one from Theme.Provide.
ZIndex UsedAs<number> ❌ - Z index of the component.
Target Instance ✅ - The element to point at.
Open UsedAs<boolean> ❌ - Whether the coachmark is shown. Pass a Value so the card can close itself.
Title string ❌ - Heading of the card.
Text string ❌ - Text of the card.
Step string ❌ - Small caption above the title, such as "1 of 3".
ActionText string ❌ "Got it" Label of the button. It also dismisses the coachmark.
Placement TooltipPlacement ❌ "Auto" Preferred side of the target for the card.
Spotlight boolean ❌ true Dim everything except the target.
Dim number ❌ 0.55 How dark the scrim is, from 0 to 1.
DismissOnScrim boolean ❌ false Close the coachmark when the dimmed area is pressed.
TargetPadding number ❌ 6 Space in pixels around the cut-out.
Gap number ❌ 16 Space in pixels between the target and the card.
Width number ❌ 280 Width of the card in pixels.
Tone "Primary" \| "Surface" ❌ "Primary" "Primary" for a card in the brand colour, "Surface" for a plain card.

Callbacks

Name Description
OnAction: () -> () Runs when the button is pressed.
OnDismiss: () -> () Runs when the coachmark closes.

See also