Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

A 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.
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.
Show code
<app-button onclick="WUI.tour.start('orders-intro')">Start the tour</app-button>
<app-tour id="orders-intro" tour-id="orders-intro">
    <app-tour-step target="#search" title="Search">Find any record by name or number.</app-tour-step>
    <app-tour-step target="#filters" title="Filters">Narrow the list to what you need.</app-tour-step>
    <app-tour-step target="#export">Download what you see as a spreadsheet.</app-tour-step>
</app-tour>

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.
Projects hold your sites, budgets and milestones. Use the name your team says on site. Create it here. You can change everything later.
Show code
<app-tour id="new-project" tour-id="new-project">
    <app-tour-step target="#new-project" title="Start a project" advance-on="AppTourStepAdvanceOn.Click">Projects hold your sites, budgets and milestones.</app-tour-step>
    <app-tour-step target="#project-name" title="Name it">Use the name your team says on site.</app-tour-step>
    <app-tour-step target="#create-project">Create it here. You can change everything later.</app-tour-step>
</app-tour>

<script>
    document.getElementById('new-project').addEventListener('wui-tour:beforestep', (e) => {
        if (e.detail.step.target === '#project-name') e.detail.wait(openForm());
    });
</script>
Your own words
action-label names the control in place of its accessible name, and advance-label changes the sentence.
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.
Show code
<app-tour id="adv-words-tour" tour-id="adv-words" advance-label="Press {actionName} to go on.">
    <app-tour-step target="#search" title="Search" advance-on="AppTourStepAdvanceOn.Click" action-label="Search records">Find any record by name or number.</app-tour-step>
    ...
</app-tour>

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.
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.
Show code
<app-tour id="orders-intro" tour-id="orders-intro" seen-store="AppTourSeenStore.Local">...</app-tour>
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.
Show code
<script>
    WUI.tour.seenStore = {
        isSeen: (tourId) => fetch(`/me/tours/${tourId}`).then((r) => r.json()).then((j) => j.seen),
        markSeen: (tourId, outcome) => fetch(`/me/tours/${tourId}`, {
            method: 'PUT',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ outcome }),
        }).then(() => undefined),
    };
</script>

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.
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.
Show code
<app-tour-step target="#search" title="Search" media="/tour/new-project.webp" media-alt="The New project form, filled in">Find any record by name or number.</app-tour-step>
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.
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.
Show code
<app-tour id="orders-intro" tour-id="orders-intro" media-pause-label="Pause the clip" media-play-label="Play the clip">
    <app-tour-step target="#search" title="Search" media="/tour/new-project.mp4" media-type="AppTourStepMediaType.Video"
                   media-poster="/tour/new-project.webp" media-alt="Creating a project">Find any record by name or number.</app-tour-step>
    ...
</app-tour>

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
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.
Show code
<app-tour id="orders-intro" tour-id="orders-intro"
          end-title="Your workspace is ready"
          end-message="Start with New project, or open any row to see its milestones."
          end-button="Start working">...</app-tour>
Without the dialog
The last step's button reads done-label, and the tour closes as soon as it is pressed.
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.
Show code
<app-tour id="orders-intro" tour-id="orders-intro" end-dialog="false" done-label="Got it">...</app-tour>
With a next step
The full-width button closes the tour as next, then goes to the address.
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.
Show code
<app-tour id="orders-intro" tour-id="orders-intro" end-next-label="Create your first project" end-next-href="#/AppTour">...</app-tour>

Every option

Every value of every prop, one cell each.

labels

built-in labels (default)
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.
custom labels
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.
progress-label="{current} / {total}" (default "Step {current} of {total}")
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.
advance-label="Press {actionName} to go on." (default "Click {actionName} to continue.")
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.
media-pause-label="Pause the clip" (default "Pause animation")
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.
media-play-label="Play the clip" (default "Play animation")
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.
end-title="All done" (default "You're all set")
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.
end-message="Enjoy the new screen." (default "a short friendly line")
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.
end-button="Close" (default "Done")
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.
end-next-label="Create your first project" (no default; shows with end-next-href)
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.

steps

step with a title
Find any record by name or number.
step without a title
Find any record by name or number.
target hidden, step dropped
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.

open

auto-start off (default), set by Start the tour (React: open={false})
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.
auto-start="true", starts at page load (React: open={true})
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.
id, the element WUI.tour.start targets (React: open)
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.

onClose

wui-tour:close, runs when the tour ends with its reason (React: onClose)
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.

tourId

tour-id, names the tour in the seen store (no visible effect without one)
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.

seenStore

no store (default)
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.
browser storage, seen-store="local"
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.
WUI.tour.seenStore, a store you supply (React: seenStore object)
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.

onBeforeStep

wui-tour:beforestep, awaited before each step's target is looked up (React: onBeforeStep)
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.

endDialog

end-dialog on (default)
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.
end-dialog off
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.

endNextHref

no next step (default)
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.
with a next step
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.

className

class, extra classes on the tour element (no visible change)
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.

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.

three steps a picture, then a loop click to continue
none local
Find any record by name or number. Narrow the list to what you need. Download what you see as a spreadsheet.
React, generated from the controls
<AppTour
  open={open}
  onClose={() => setOpen(false)}
  tourId="pg"
  steps={steps}
/>
Razor, the same props
<app-tour id="pg-tour" tour-id="pg">…</app-tour>

19 props. The 2 most used come first.

Used on most screens 2 props

PropTypeDefaultDescription
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

PropTypeDefaultDescription
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.