Coachlight.Avalonia

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

Coachlight.Avalonia

★ 20 Open GitHub ↗

Interactive onboarding / product tours for Avalonia apps — spotlight coachmarks, modal steps, and step-by-step navigation. Zero runtime dependencies beyond Avalonia itself, MVVM-friendly, and fully re-themeable.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Coachlight.Avalonia [![NuGet](https://img.shields.io/nuget/v/Coachlight.Avalonia.svg)](https://www.nuget.org/packages/Coachlight.Avalonia/)

Interactive onboarding / product tours for [Avalonia](https://avaloniaui.net/) apps — spotlight
coachmarks, modal steps, and step-by-step navigation. Zero runtime dependencies beyond Avalonia
itself, MVVM-friendly, and fully re-themeable.

- **Spotlight coachmarks** — dims the screen and cuts a rounded hole around the target control.
  By default the target stays interactive (clicks pass through the hole) — you can even drive a
  live demo while the step is shown (see `OnEnter`/`OnExit`) — or block clicks with
  `.Interactive(false)` for a look-only step.
- **Any control can be a target** — buttons, text boxes, combo boxes, checkboxes, sliders, whole
  list boxes — targeting works off the control's actual on-screen bounds, not just buttons.
- **Several targets per step** — one coachmark can spotlight a group of controls at once, each
  with its own hole, however far apart they sit on screen.
- **Auto-flip placement** — the card tries your preferred side first and falls back to whichever
  side actually fits the window.
- **Stoppable and resumable** — `StartTour` hands back the `TourController` driving the tour, so
  you can end it early and later pick it up at the step it stopped on, numbering intact.
- **Zero dependencies** — no MVVM Toolkit, no ReactiveUI required to use the library itself.
- **MVVM-friendly** — `StartTour` takes a `Visual` anchor (e.g. via `CommandParameter`), so a
  view model never needs a direct reference to a view.
- **Fully re-themeable** — the card is a `TemplatedControl` with a default `ControlTheme`; every
  color is a `DynamicResource` you can override, and the whole template can be replaced.
- **Opt-in persistence** — show a tour once per user with a pluggable `IProgressStore`; the
  library never touches disk unless you explicitly ask it to.

https://github.com/user-attachments/assets/264ae1e3-30cd-45f3-9faf-117156bb496a

## Install

```bash
dotnet add package Coachlight.Avalonia
```

## Quickstart

**1. Reference the default theme** in `App.axaml`:

```xml
<Application.Resources>
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>
            <ResourceInclude Source="avares://Coachlight.Avalonia/Themes/Coachlight.axaml"/>
        </ResourceDictionary.MergedDictionaries>
    </ResourceDictionary>
</Application.Resources>
```

**2. Tag the controls you want to spotlight** with `Coachmark.Id`:

```xml
<Window xmlns:cl="clr-namespace:Coachlight.Avalonia.Targeting;assembly=Coachlight.Avalonia">
    <Button cl:Coachmark.Id="btnConnect" Content="Connect"/>
</Window>
```

**3. Build a tour and start it:**

```csharp
using Coachlight.Avalonia;                // StartTour extension
using Coachlight.Avalonia.Building;
using Coachlight.Avalonia.Enums;

var tour = TourBuilder.Create("demo")
    .Modal(s => s
        .Title("Welcome!")
        .Text("A short tour of the interface."))
    .Coachmark("btnConnect", s => s
        .Placement(Side.Right)
        .Title("Connect")
        .Text("This button connects to the server."))
    .Build();

anchor.StartTour(tour); // anchor: any Visual already attached to the window
```

That's it — a dimmed overlay with a spotlighted hole and a navigation card appears over the
window. See `samples/Coachlight.Gallery` for a full MVVM example: a multi-page app where every
page owns its own tour, the tours hand off to each other and resume afterwards, covering
`TextBox`, `ComboBox`, `CheckBox`, `Slider`, `ListBox`, custom button captions, and a live
auto-scroll demo.

## Targeting

Two ways to point a step at a control:

```csharp
// By id (attached property, works from anywhere — recommended)
.Coachmark("btnConnect", s => s.Title(...))

// By direct reference, resolved lazily when the step is shown
.Coachmark(() => myControl, s => s.Title(...))
```

A step with no target (`.Modal(...)`) is shown as a centered card with no spotlight.

### Several controls in one step

Pass ids (or controls) instead of one, and the step cuts a hole around each. The card is placed
beside the group as a whole, so it works even when the targets sit in opposite corners:

```csharp
.Coachmark(new[] { "btnConnect", "btnSettings" }, s => s
    .Placement(Side.Left)
    .Title("Both buttons")
    .Text("Each gets its own hole; the card sits beside the group."))

// Lazily resolved, same behavior — nulls are ignored
.Coachmark(() => new[] { ctrlA, ctrlB }, s => s.Title(...))
```

Add `.Anchor(index)` to place the card next to one specific target instead of the whole group.

## Click-through holes, and skipping missing targets

By default the spotlight hole is click-through: the user can click the highlighted control right
through it. Call `.Interactive(false)` to make the overlay swallow clicks over the hole instead —
a look-only step where the target can be seen but not touched:

```csharp
.Coachmark("btnDelete", s => s
    .Interactive(false)          // hole is dimmed-through: the button can't be clicked
    .Title("Danger zone")
    .Text("This is where you'd delete the project — but not right now."))
```

When a step's target can't be resolved (no control carries the id, the provider returned `null`,
or the control is hidden), the step is **skipped** and the tour moves on to the next showable
step. Opt out with `.SkipIfMissing(false)` to keep the step and show it as a centered card
instead:

```csharp
.Coachmark("maybeMissing", s => s
    .SkipIfMissing(false)        // shown as a centered card even if the target isn't there
    .Title("Optional feature")
    .Text("Shown even when this control isn't on screen."))
```

## Resuming a tour, and handing off between tours

`StartTour` returns the `TourController` driving the tour: use it to watch the tour or to end it
programmatically. Combined with `startIndex`, that is enough to interrupt a tour and continue it
later — the card keeps counting against the whole tour ("6 / 7"), not against the leftover steps.

```csharp
var controller = anchor.StartTour(tour);

controller.Ended += (_, reason) => { /* Completed, Skipped or Stopped */ };
controller.Stop();                       // ends it; reports Stopped, no OnSkipped callback

anchor.StartTour(tour, startIndex: 5);   // later: continue from step 5, card reads "6 / 7"
```

This is what the gallery sample builds on: each page has its own view model and its own tour, a
step asks the user to press a real button (clicks pass through the spotlight), and that press
stops the current tour and starts the next page's one. When the second tour completes, the first
resumes one step past where it handed off.

## Localizing button captions

```csharp
TourBuilder.Create("demo")
    .Labels(new TourLabels
    {
        Skip = "Überspringen",
        Back = "Zurück",
        Next = "Nächste",
        Done = "Erledigt",
    })
    ...
```

## Live demos on a step (`OnEnter` / `OnExit`)

```csharp
.Coachmark("recentItemsList", s => s
    .Title("Recent items")
    .Text("Watch it scroll by itself.")
    .OnEnter(() => StartAutoScroll(anchor))
    .OnExit(() => StopAutoScroll(anchor)))
```

`OnEnter` runs when the step becomes active, `OnExit` when the user navigates away (or the tour
ends) — exceptions thrown from either are swallowed so a broken demo can't break navigation.

## Showing a tour only once

`StartTour(anchor, tour)` shows the tour every time it's called. To show it once per user, pass
an `IProgressStore` — the bundled `JsonProgressStore` persists to a JSON file under the OS
application-data folder:

```csharp
static readonly IProgressStore Store = new JsonProgressStore();

anchor.StartTour(tour, Store);              // shown once; no-op afterwards
anchor.StartTour(tour, Store, force: true);  // always shown (e.g. a "?" help button)
```

This overload returns `null` when the store reports the tour as already completed and nothing is
shown; otherwise it returns the `TourController`, same as above.

Implement `IProgressStore` yourself to persist elsewhere (a database, cloud settings, etc.).

## Customizing the look

Every color used by the default theme is a `DynamicResource` — override the keys in your own
resources to restyle without touching the template:

```xml
<SolidColorBrush x:Key="CoachlightAccentBrush" Color="#FF16A34A"/>
<SolidColorBrush x:Key="CoachlightCardBackgroundBrush" Color="#FF202020"/>
```

Keys: `CoachlightDimBrush`, `CoachlightCardBackgroundBrush`, `CoachlightCardBorderBrush`,
`CoachlightForegroundBrush`, `CoachlightSecondaryForegroundBrush`, `CoachlightAccentBrush`,
`CoachlightAccentForegroundBrush`. Light/dark variants are provided via `ThemeDictionaries` and
switch automatically with `ActualThemeVariant`.

For structural changes, provide your own `ControlTheme` keyed `{x:Type controls:CoachmarkCard}`
(`xmlns:controls="clr-namespace:Coachlight.Avalonia.Controls;assembly=Coachlight.Avalonia"`) —
`CoachmarkCard` exposes `Title`, `Content`, `ProgressText`, `IsFirst`, `IsLast`, `SkipText`,
`BackText`, `NextText`, `SkipCommand`, `PreviousCommand`, `NextCommand` for the template to bind.

## License

MIT — see [LICENSE](LICENSE).

Coachlight.Avalonia

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README