HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
TourView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA guided tour of an interface, one stop at a time.StableSince 0.1.0OverlaysUsageimport'@fusion.dev/helix/tour'import'@fusion.dev/helix-headless/tour'Preview
API ReferenceRoothelix-tourA guided tour of an interface, one stop at a time.
PropTypeDescriptionbackLabelstringDefault""Label for the control that goes back, passed to every stop.defaultIndexnumberDefault0The stop to start on, when nothing else sets one.defaultOpenbooleanDefaultfalseWhether the element starts open. Ignored once open is written.doneLabelstringDefault""Label for the control that goes on from the last stop.indexnumberThe index of the stop being shown.labelstringDefault""The tour's name, read by screen readers, such as "Getting started".nextLabelstringDefault""Label for the control that goes on.openbooleanWhether the element is open.outsidePress"block"|"close"What a press outside the current stop and its target does while the tour
runs. Unset, nothing: the page stays usable. close ends the tour, as
Skip does, and block refuses the press.progressbooleanDefaultfalseDraws each stop's place in the run in its panel, as well as saying it.progressLabelstringDefault"{index} of {count}"Each stop's place in the run, with {index} and {count} filled in and
written in the locale. Translate it with the rest of your text.skipLabelstringDefault""Label for the control that leaves the tour.spotlightPaddingnumberDefault8The space around the target inside the spotlight, in pixels.
ReadTypeDescriptionlengthnumberHow many stops there are.stopsHelixHeadlessTourStop[]The stops, in source order.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The stops, in the order they are shown.
EventTypeDescriptionhelix-activateHelixActivateEventFired after the current stop changes, with the new index.helix-before-activateHelixBeforeActivateEventFired before the current stop changes, with the new index. Cancelable: call preventDefault() to stay on the current stop.helix-before-closeHelixBeforeCloseEventFired before the user ends the tour early. Cancelable: call preventDefault() to keep the tour open.helix-before-openHelixBeforeOpenEventFired before requestOpen(true) starts the tour. Cancelable: call preventDefault() to keep it closed.helix-completeHelixCompleteEventFired when the last stop is finished.helix-tour-askHelixTourAskEventFired when a stop's control is pressed to move the tour. The stop sends it, and the tour handles it.helix-tour-statusHelixTourStatusEventFired when the tour starts waiting at a wait stop, is skipped, or is completed, with the stop's index and detail.status saying which.toggleToggleEventSent when the tour starts or ends, with newState and oldState.
MethodTypeDescriptionback() => voidGoes to the previous stop, passing over a wait stop, which shows nothing.
It does nothing on the first stop, or where only wait stops come before.next() => voidGoes to the next stop, and finishes the tour on the last stop.requestOpen(next: boolean) => booleanRequests that the element open or close, and returns whether the change
was applied.skip() => voidEnds the tour early, as a close. helix-complete is not fired.toggleOpen() => booleanRequests the opposite of the current state.
PartDescriptionbackdropBehind a dialog or a floating stop, which lights nothing. It draws no box until you give it one.spotlightThe box over the current target. It also draws the dimmed area around the target.
CSS PropertyDescription--tour-scrim-colorThe color of the dimmed area outside the spotlight.--tour-spotlight-heightThe lit box's height, in pixels, padding included. Written on the spotlight while it lights a target.--tour-spotlight-radiusThe corner radius of the spotlight.--tour-spotlight-widthThe lit box's width, in pixels, padding included. Written on the spotlight while it lights a target.--tour-spotlight-xThe lit box's left edge, from the window's left edge, in pixels. Written on the spotlight while it lights a target.--tour-spotlight-yThe lit box's top edge, from the window's top edge, in pixels. Written on the spotlight while it lights a target.
Custom stateDescriptionopenWhile the tour is running.preparingWhile the tour waits for the current stop's effect before showing the stop.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.waitingWhile the tour waits at a wait stop for its target to be on the page.
Stophelix-tour-stopOne stop on a tour: the element it points at, and a panel of content about it.
PropTypeDescriptionbackLabelstringDefault"Back"Label for the control that goes back.currentbooleanDefaultfalseWhether the stop is the one being shown.doneLabelstringDefault"Done"Label for the control that goes on from the last stop.effectTourStopEffectRun as the tour reaches the stop, before it is shown: see the description
above. A function, so it is set from script and has no attribute.firstbooleanDefaultfalseWhether the stop is the first one, with no stop before it.forstringDefault""The id of the element the stop points at.labelstringDefault""The panel's name, where neither the heading slot nor the content holds a
heading.lastbooleanDefaultfalseWhether the stop is the last one. Its next control then shows doneLabel.nextLabelstringDefault"Next"Label for the control that goes on.placement"bottom"|"bottom-end"|"bottom-start"|"left"|"left-end"|"left-start"|"right"|"right-end"|"right-start"|"top"|"top-end"|"top-start"Default"bottom"The side of the target the panel is placed on when there is room.skipLabelstringDefault"Skip"Label for the control that leaves the tour.type"dialog"|"floating"|"wait"What kind of stop this is. Unset, it is a bubble pointing at its target.
ReadTypeDescriptiontargetHTMLElement|nullThe element the stop points at, or null when no element has the for id.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The stop's content. Any content works, such as a card, or a heading and a line.actionsReplaces the controls, which are Back, Next, and Skip.descriptionA line under the title, which describes the panel.headingThe stop's title, which names the panel.
EventTypeDescriptionhelix-tour-askHelixTourAskEventFired when one of the stop's controls is pressed, to move the tour.
MethodTypeDescriptionfocus(options: FocusOptions) => voidMoves focus to the panel while the stop is shown.
PartDescriptionactionsThe row the controls sit in.arrowThe arrow that points at the target.arrow-bottomThe arrow while the panel is below its target, on the panel's top edge. Applied with arrow.arrow-leftThe arrow while the panel is left of its target, on the panel's right edge. Applied with arrow.arrow-rightThe arrow while the panel is right of its target, on the panel's left edge. Applied with arrow.arrow-topThe arrow while the panel is above its target, on the panel's bottom edge. Applied with arrow.backThe control that goes to the previous stop.back-buttonThe button inside back.back-liveThe live region inside back.back-spinnerThe ring back turns while it is pending.back-textThe words on that button, trimmed to their capitals and baseline.contentThe region holding the slotted content.descriptionThe slot the description is in. It draws no box until you give it one.headingThe slot the title is in. It draws no box until you give it one.nextThe control that goes to the next stop, and finishes the tour on the last stop.next-buttonThe button inside next.next-liveThe live region inside next.next-spinnerThe ring next turns while it is pending.next-textThe words on that button, trimmed to their capitals and baseline.progressThe stop's place in the tour, such as "2 of 5". It describes the panel, and is shown when the tour has progress.skipThe control that ends the tour early.skip-buttonThe button inside skip.skip-liveThe live region inside skip.skip-spinnerThe ring skip turns while it is pending.skip-textThe words on that button, trimmed to their capitals and baseline.surfaceThe panel that points at the target.
CSS PropertyDescription--tour-arrow-sizeThe size of the arrow's box, before it is rotated.--tour-border-widthThe width of the panel's border. It follows --helix-border-floating, which is 0, so the panel stands out by its shadow unless a theme sets a border.--tour-bubble-sizeThe widest the panel can grow.--tour-paddingThe padding inside the panel.--tour-shadowThe shadow under the panel. It follows --helix-shadow-floating. The panel can sit over any content, so it has a shadow by default.--tour-surface-colorThe color of the panel's surface.
Custom stateDescriptionenteringFrom the moment the stop is shown until its entrance has finished.exitingFrom the moment the stop is left until its exit has finished.placed-bottomThe panel sits below its target.placed-leftThe panel sits to the left of its target.placed-rightThe panel sits to the right of its target.placed-topThe panel sits above its target.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-tourA guided tour of an interface, one stop at a time.
PropTypeDescriptionbackLabelstringDefault""Label for the control that goes back, passed to every stop.defaultIndexnumberDefault0The stop to start on, when nothing else sets one.defaultOpenbooleanDefaultfalseWhether the element starts open. Ignored once open is written.doneLabelstringDefault""Label for the control that goes on from the last stop.indexnumberThe index of the stop being shown.labelstringDefault""The tour's name, read by screen readers, such as "Getting started".nextLabelstringDefault""Label for the control that goes on.openbooleanWhether the element is open.outsidePress"block"|"close"What a press outside the current stop and its target does while the tour
runs. Unset, nothing: the page stays usable. close ends the tour, as
Skip does, and block refuses the press.progressbooleanDefaultfalseDraws each stop's place in the run in its panel, as well as saying it.progressLabelstringDefault"{index} of {count}"Each stop's place in the run, with {index} and {count} filled in and
written in the locale. Translate it with the rest of your text.skipLabelstringDefault""Label for the control that leaves the tour.spotlightPaddingnumberDefault8The space around the target inside the spotlight, in pixels.
ReadTypeDescriptionlengthnumberHow many stops there are.stopsHelixHeadlessTourStop[]The stops, in source order.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The stops, in the order they are shown.
EventTypeDescriptionhelix-activateHelixActivateEventFired after the current stop changes, with the new index.helix-before-activateHelixBeforeActivateEventFired before the current stop changes, with the new index. Cancelable: call preventDefault() to stay on the current stop.helix-before-closeHelixBeforeCloseEventFired before the user ends the tour early. Cancelable: call preventDefault() to keep the tour open.helix-before-openHelixBeforeOpenEventFired before requestOpen(true) starts the tour. Cancelable: call preventDefault() to keep it closed.helix-completeHelixCompleteEventFired when the last stop is finished.helix-tour-askHelixTourAskEventFired when a stop's control is pressed to move the tour. The stop sends it, and the tour handles it.helix-tour-statusHelixTourStatusEventFired when the tour starts waiting at a wait stop, is skipped, or is completed, with the stop's index and detail.status saying which.toggleToggleEventSent when the tour starts or ends, with newState and oldState.
MethodTypeDescriptionback() => voidGoes to the previous stop, passing over a wait stop, which shows nothing.
It does nothing on the first stop, or where only wait stops come before.next() => voidGoes to the next stop, and finishes the tour on the last stop.requestOpen(next: boolean) => booleanRequests that the element open or close, and returns whether the change
was applied.skip() => voidEnds the tour early, as a close. helix-complete is not fired.toggleOpen() => booleanRequests the opposite of the current state.
PartDescriptionbackdropBehind a dialog or a floating stop, which lights nothing. It draws no box until you give it one.spotlightThe box over the current target. It also draws the dimmed area around the target.
CSS PropertyDescription--tour-spotlight-heightThe lit box's height, in pixels, padding included. Written on the spotlight while it lights a target.--tour-spotlight-widthThe lit box's width, in pixels, padding included. Written on the spotlight while it lights a target.--tour-spotlight-xThe lit box's left edge, from the window's left edge, in pixels. Written on the spotlight while it lights a target.--tour-spotlight-yThe lit box's top edge, from the window's top edge, in pixels. Written on the spotlight while it lights a target.
Custom stateDescriptionopenWhile the tour is running.preparingWhile the tour waits for the current stop's effect before showing the stop.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.waitingWhile the tour waits at a wait stop for its target to be on the page.
Stophelix-headless-tour-stopOne stop on a tour: the element it points at, and a panel of content about it.
PropTypeDescriptionbackLabelstringDefault"Back"Label for the control that goes back.currentbooleanDefaultfalseWhether the stop is the one being shown.doneLabelstringDefault"Done"Label for the control that goes on from the last stop.effectTourStopEffectRun as the tour reaches the stop, before it is shown: see the description
above. A function, so it is set from script and has no attribute.firstbooleanDefaultfalseWhether the stop is the first one, with no stop before it.forstringDefault""The id of the element the stop points at.labelstringDefault""The panel's name, where neither the heading slot nor the content holds a
heading.lastbooleanDefaultfalseWhether the stop is the last one. Its next control then shows doneLabel.nextLabelstringDefault"Next"Label for the control that goes on.placement"bottom"|"bottom-end"|"bottom-start"|"left"|"left-end"|"left-start"|"right"|"right-end"|"right-start"|"top"|"top-end"|"top-start"Default"bottom"The side of the target the panel is placed on when there is room.skipLabelstringDefault"Skip"Label for the control that leaves the tour.type"dialog"|"floating"|"wait"What kind of stop this is. Unset, it is a bubble pointing at its target.
ReadTypeDescriptiontargetHTMLElement|nullThe element the stop points at, or null when no element has the for id.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The stop's content. Any content works, such as a card, or a heading and a line.actionsReplaces the controls, which are Back, Next, and Skip.descriptionA line under the title, which describes the panel.headingThe stop's title, which names the panel.
EventTypeDescriptionhelix-tour-askHelixTourAskEventFired when one of the stop's controls is pressed, to move the tour.
MethodTypeDescriptionfocus(options: FocusOptions) => voidMoves focus to the panel while the stop is shown.
PartDescriptionactionsThe row the controls sit in.arrowThe arrow that points at the target.arrow-bottomThe arrow while the panel is below its target, on the panel's top edge. Applied with arrow.arrow-leftThe arrow while the panel is left of its target, on the panel's right edge. Applied with arrow.arrow-rightThe arrow while the panel is right of its target, on the panel's left edge. Applied with arrow.arrow-topThe arrow while the panel is above its target, on the panel's bottom edge. Applied with arrow.backThe control that goes to the previous stop.back-buttonThe button inside back.back-liveThe live region inside back.back-spinnerThe ring back turns while it is pending.back-textThe words on that button, trimmed to their capitals and baseline.contentThe region holding the slotted content.descriptionThe slot the description is in. It draws no box until you give it one.headingThe slot the title is in. It draws no box until you give it one.nextThe control that goes to the next stop, and finishes the tour on the last stop.next-buttonThe button inside next.next-liveThe live region inside next.next-spinnerThe ring next turns while it is pending.next-textThe words on that button, trimmed to their capitals and baseline.progressThe stop's place in the tour, such as "2 of 5". It describes the panel, and is shown when the tour has progress.skipThe control that ends the tour early.skip-buttonThe button inside skip.skip-liveThe live region inside skip.skip-spinnerThe ring skip turns while it is pending.skip-textThe words on that button, trimmed to their capitals and baseline.surfaceThe panel that points at the target.
Custom stateDescriptionenteringFrom the moment the stop is shown until its entrance has finished.exitingFrom the moment the stop is left until its exit has finished.placed-bottomThe panel sits below its target.placed-leftThe panel sits to the left of its target.placed-rightThe panel sits to the right of its target.placed-topThe panel sits above its target.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionEventsA stop asks to move, the tour decides, and finishing fires a different event from leaving.First And LastThe first and last stops, marked first and last, with more space around their targets.Inside A Menu And DrawerA path that opens a menu and a drawer to point at what is inside them.PreviewFour stops across an app shell, each holding a card.PreviewFour stops across an app shell, each holding a card.RelabeledThe labels of the four controls, set once on the tour.With ActionsYour own controls, with a count of the current stop.