On this page
@addTagHelper *, Webority.Ui.RazorA guided tour
Use a tour to walk someone through a screen, one highlighted part at a time.
Three steps
Start it, then use Next and Back, the arrow keys, or Escape. Tab stays inside the card. A step whose target is hidden is dropped and left out of the count, so the count shows only the steps that show. If no step has a visible target the tour closes with noTargets and nothing is marked seen.
Click to continue
Make a step wait for the person to use the control it names, so they learn by doing.
Open the form, then fill it
The first step waits for New project. Its click opens the form, and a wui-tour:beforestep listener waits for the form, so the next step finds the name field. Next opens the form too.
Your own words
action-label names the control in place of its accessible name, and advance-label changes the sentence.
Remembering it was seen
Keep seen-state in the browser so a tour does not start again for the same person.
Browser storage
Finish or skip this tour once and it will not start again in this browser. The next start then closes straight away with the reason alreadySeen; clear the wui-tour-seen:seen key in your browser's storage to see it again.
A store on your server
Any object with those two async methods works, so the same record can serve the web and the mobile tour. The tour asks isSeen before it shows anything and calls markSeen with the outcome when it is finished or skipped, never when it closes as alreadySeen or noTargets. With the closing dialog on, a finished tour is marked as the dialog opens, so a reload while it shows does not start the tour again.
Pictures and loops
Show a picture or a short muted loop at the top of a step card, with a text alternative.
A picture on a step
The file is scaled to cover a 16:9 frame the width of the card, which keeps its size while the file loads, so a 16:9 file shows whole.
A short loop
Muted, inline and looped, with a pause button. Under reduced motion it waits on its poster with a play button. Keep a loop to a few seconds; it never plays sound.
A welcome card
React only: every Razor app-tour-step needs a target, so a Razor tour has no welcome card.
The closing dialog
Choose the words of the closing dialog, or leave it out when the last step ends the walk.
Your own closing text
Without the dialog
The last step's button reads done-label, and the tour closes as soon as it is pressed.
With a next step
The full-width button closes the tour as next, then goes to the address.
Every option
Every value of every prop, one cell each.
labels
built-in labels (default)
custom labels
progress-label="{current} / {total}" (default "Step {current} of {total}")
advance-label="Press {actionName} to go on." (default "Click {actionName} to continue.")
media-pause-label="Pause the clip" (default "Pause animation")
media-play-label="Play the clip" (default "Play animation")
end-title="All done" (default "You're all set")
end-message="Enjoy the new screen." (default "a short friendly line")
end-button="Close" (default "Done")
end-next-label="Create your first project" (no default; shows with end-next-href)
steps
step with a title
step without a title
target hidden, step dropped
open
auto-start off (default), set by Start the tour (React: open={false})
auto-start="true", starts at page load (React: open={true})
id, the element WUI.tour.start targets (React: open)
onClose
wui-tour:close, runs when the tour ends with its reason (React: onClose)
tourId
tour-id, names the tour in the seen store (no visible effect without one)
seenStore
no store (default)
browser storage, seen-store="local"
WUI.tour.seenStore, a store you supply (React: seenStore object)
onBeforeStep
wui-tour:beforestep, awaited before each step's target is looked up (React: onBeforeStep)
endDialog
end-dialog on (default)
end-dialog off
endNextHref
no next step (default)
with a next step
className
class, extra classes on the tour element (no visible change)
Guidance
What to do, and what to avoid.
Use it when
- A person meets a screen for the first time and a handful of controls need a one-line explanation each.
- A new feature needs pointing out where it sits on a screen people already know.
- The steps follow a natural order the person can walk in under a minute.
- The tour teaches one clear first action, such as creating the first item: give the closing dialog a next step (endNextLabel with endNextHref) that goes to it. With no single clear action, leave the dialog with Done alone.
Reach for something else when
- You need to explain one control, on demand. → AppTooltip
- You are collecting information in steps. → AppWizard
- You want a closable note with a link, not a walk. → AppPopover
Reference
Try every prop, read the full list, and check keyboard and screen reader behaviour.
19 props. The 2 most used come first.
Used on most screens 2 props
| Prop | Type | Default | Description |
|---|---|---|---|
| tour-iddefault - | string | - | Names the tour in the seen store. |
| seen-storedefault - | local | - | Keep seen-state in the browser's localStorage. Omit it to use WUI.tour.seenStore when one is set, or none. |
Less common 17 props
| Prop | Type | Default | Description |
|---|---|---|---|
| iddefault required | string | required | The element id WUI.tour.start targets. |
| auto-startdefault false | bool | false | Start the tour when the page loads. React starts it from open. |
| back-labeldefault Back | string | Back | Back button text. |
| next-labeldefault Next | string | Next | Next button text. |
| skip-labeldefault Skip | string | Skip | Skip button text. |
| done-labeldefault Done | string | Done | The last step's button text with end-dialog="false". While the closing dialog is on, the last step reads next-label, because the dialog follows. |
| progress-labeldefault Step {current} of {total} | string | Step {current} of {total} | The step count template. |
| advance-labeldefault Click {actionName} to continue. | string | Click {actionName} to continue. | A click step's sentence. {actionName} is the step's action-label, or else its target's accessible name. |
| media-pause-labeldefault Pause animation | string | Pause animation | The name of a step loop's pause button while the loop plays. |
| media-play-labeldefault Play animation | string | Play animation | The name of that button while the loop is paused. |
| end-dialogdefault true | bool | true | Show the closing dialog after the last step. |
| end-titledefault You're all set | string | You're all set | The closing dialog's title. |
| end-messagedefault a short friendly line | string | a short friendly line | The closing dialog's message. |
| end-buttondefault Done | string | Done | The closing dialog's button text. |
| end-next-labeldefault - | string | - | The closing dialog's next step button text. Shows only with end-next-href; the button closes the tour as next, then goes to the address. |
| end-next-hrefdefault - | string | - | Where the closing dialog's next step goes. Shows only with end-next-label. |
| classdefault - | string | - | Extra classes on the element; passes through as a plain HTML attribute (no dedicated tag helper property). |
Screen reader
3 notes- Focus moves into the card on open, stays there while the tour runs and returns to where it was on close; each step is announced.
- Escape skips the tour, and the arrow keys move between steps except while focus is in a field.
- On a phone the card sits on the side of the target with room and never covers it; the closing dialog says the tour is done, and Escape there closes the tour as finished.