# Coach mark

A Popover that guides users step-by-step through key aspects of new features.

Tabs: [Guidelines](/components/web/coach-mark/coach-mark.guidelines.md) · [Code](/components/web/coach-mark/coach-mark.code.md)

## Basic usage

`CoachMark` wraps a [Popover](/components/web/popover/popover.guidelines). Wrap the element you want to highlight in `CoachMark.Anchor` and put the step in `CoachMark.Content`. The coach mark is open by default.

```tsx
import {Button, CoachMark, Text} from '@pleo-io/telescope'
;<CoachMark>
    <CoachMark.Anchor>
        <Button variant="primary">Upload receipt</Button>
    </CoachMark.Anchor>
    <CoachMark.Content>
        <CoachMark.Header>
            <CoachMark.Title>Get your expenses covered!</CoachMark.Title>
        </CoachMark.Header>
        <CoachMark.Body>
            <Text variant="body-m">Upload your receipts directly from the app.</Text>
        </CoachMark.Body>
        <CoachMark.Footer>
            <CoachMark.StepInfo>1 of 3</CoachMark.StepInfo>
            <CoachMark.Actions>
                <CoachMark.Dismiss onClick={onDismiss}>Dismiss</CoachMark.Dismiss>
                <CoachMark.Next onClick={onNext}>Next</CoachMark.Next>
            </CoachMark.Actions>
        </CoachMark.Footer>
    </CoachMark.Content>
</CoachMark>
```

Coach marks are made for multi-step guidance and feature tours. For a single, dismissible hint, use [Feature tip](/components/web/feature-tip/feature-tip.guidelines) instead.

## Tour flow

`CoachMark` doesn't manage steps. Keep the current step in state and render the coach mark only around the element of the current step. Render the other elements without it.

```tsx
const [showTour, setShowTour] = React.useState(false)
const [currentStep, setCurrentStep] = React.useState(1)

const TourStep = ({step, children}: {step: number; children: React.ReactNode}) => {
    if (!showTour || step !== currentStep) {
        return <>{children}</>
    }

    return (
        <CoachMark withBackdrop>
            <CoachMark.Anchor>{children}</CoachMark.Anchor>
            <CoachMark.Content>{/* step content */}</CoachMark.Content>
        </CoachMark>
    )
}
```

Use `open` to show and hide a coach mark that stays mounted.

## Backdrop

Set `withBackdrop` to dim the rest of the page. The anchored element stays above the backdrop.

## Secondary actions

Use `CoachMark.Secondary` for an extra action next to `CoachMark.Next`, for example a help link.

```tsx
<CoachMark.Footer>
    <CoachMark.StepInfo>2 of 3</CoachMark.StepInfo>
    <CoachMark.Actions>
        <CoachMark.Secondary onClick={openHelpArticle}>Need more help?</CoachMark.Secondary>
        <CoachMark.Next>Next</CoachMark.Next>
    </CoachMark.Actions>
</CoachMark.Footer>
```

## Top action

Use `CoachMark.TopAction` to place an action, such as a close button, next to the header and body.

```tsx
<CoachMark.TopAction
    action={
        <IconButton
            variant="quiet"
            size="small"
            Icon={Close}
            onClick={onClose}
            tooltipProps={{dangerouslyOmitTooltip: true, 'aria-label': 'Close'}}
        />
    }
>
    <CoachMark.Header>
        <CoachMark.Title>Get your expenses covered!</CoachMark.Title>
    </CoachMark.Header>
    <CoachMark.Body>
        <Text variant="body-m">Upload your receipts directly from the app.</Text>
    </CoachMark.Body>
</CoachMark.TopAction>
```

## Subcomponents

| Component             | Description                                                                                                           |
| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `CoachMark.Anchor`    | Wraps the highlighted element. The coach mark points at it.                                                           |
| `CoachMark.Content`   | The popover with an arrow. Accepts Popover `Content` props except `align` and `sideOffset`. `side` defaults to `top`. |
| `CoachMark.Header`    | Wraps the title.                                                                                                      |
| `CoachMark.Title`     | A `heading-m` [Text](/components/web/text/text.guidelines).                                                           |
| `CoachMark.Body`      | The step description.                                                                                                 |
| `CoachMark.TopAction` | Places `action` next to its children.                                                                                 |
| `CoachMark.Footer`    | A row with the step info and the actions.                                                                             |
| `CoachMark.StepInfo`  | The step counter, for example "1 of 3".                                                                               |
| `CoachMark.Actions`   | A [ButtonGroup](/components/web/button/button.guidelines) aligned to the end.                                         |
| `CoachMark.Next`      | A primary Button.                                                                                                     |
| `CoachMark.Dismiss`   | A tertiary Button.                                                                                                    |
| `CoachMark.Secondary` | A tertiary Button.                                                                                                    |

## Accessibility

- The content is rendered in a [Popover](/components/web/popover/popover.guidelines), which moves focus into it when it opens and is reachable with the keyboard.
- Give `CoachMark.Content` an accessible name, for example with `aria-label` or `aria-labelledby` pointing at the title.
- Give icon-only actions, such as a close `IconButton` in `CoachMark.TopAction`, an `aria-label`.

## API reference

A popover that guides users step by step through a feature. Compose it with `CoachMark.Anchor` around the highlighted element and `CoachMark.Content` for the step. For a single, dismissible hint use `FeatureTip` instead.

#### `open`

Type: `boolean`

Default: `true`

Whether the coach mark is shown. Control it to step through a tour.

#### `withBackdrop`

Type: `boolean`

Default: `false`

Dims the rest of the page behind the anchored element and the coach mark.