Walkthrough

This Angular model is inspired in part by ng-walkthrough for AngularJS.

Installation

npm i angular-walkthrough --save

Requirements

Angular 18.0 and more
Angular/cdk 18.0 and more

Old versions:

For Angular 6~11 use 0.8.2
For Angular 11~15 use 0.9.8
For Angular 16~17 use 0.10.2

Demo

See a demo.

Usage

`ng-walkthrough` attributes

All attributes are optional.

id: HTML id.

Output events

ready: fired when the walkthrough is completely ready
closed: fired when the walkthrough has been closed. It sends a boolean value set to true if the walkthrough has been closed with the "finishButton" button.
finished: fired when the walkthrough has been finished, which means : closed on last step.

Focus zone:

focusElementSelector: CSS selector for focus a HTML element. If the selector detect more that one, the only the first will be chosen.
focusElementCSSClass: Add a class on focusElement
focusHighlightAnimation: true for show highlight animation on the focus element. By default false.
focusBackdrop: true for show a dark backdrop around the focus element. By default false.
focusGlow: true for show a glow on the focus element. By default false.
focusClick: add an action click on the highlight zone.
typeSelector: type of selection. Two modes possible: element (one unique HTML element), zone (a zone with contains the first and last element). By default : element.
radius: apply a “borderRadius” on highlight zone. If number the value as change in percent. If auto use the focused element borderRadius. If it's a simple string, use it without changes. By default, no radius.
marginZone: add a margin of focus zone in px. (e.g. 12 15 12 13 for CSS 12px 15px 12px 13px, 12 15 for 12px 15px 12px 15px, 12 for 12px 12px 12px 12px.)
scrollOnTarget: if the walkthrough detects that focusElementSelector is outside of the current view, scrolls automatically. By default : true
visibilityCallback: callback to check if focusElementSelector is hidden, only if the walkthrough needs specific verification. By default : optional
notScrollOnResize: do not scroll when resizing (e.g. may be required with dynamic menu on mobile)
observerOptions: options of DOM detection changes (default: { attributes: false, childList: true, subtree: true })

Content:

contentTemplate: add a ng-template with your description.
contentText: show a simple description without formatting in content.
contentStyle: background style for content container. By default : darken. Possible values: none, darken.
alignContent: align the contentTemplate horizontally. . By default : left.
- left : on the left
- center : on the center of the page
- right: on the right
- content: center to the target content
verticalAlignContent: align the contentTemplate vertically. By default : top. Possible values :
- With target :
  - above : above content
  - top : top of content
  - center : center of content
  - bottom : bottom of content
  - below : below content
  - top-screen-center : no effect
- Without target
  - above or top : top of the page
  - center : center of the page
  - bottom or below : bottom of the page
  - top-screen-center : center on the screen with scroll on top
contentSpacing: The max space which separates the content to the focus zone horizontally, default is 0 (opposite of the focusZone)
verticalContentSpacing: The max space which separates the content to the focus zone vertically, default is 50
rootElement: root element on which walkthrough will scroll to after each positioning, as to avoid hidden zones

Navigation:

hidePrevious: true to hide the previous button. By default false
previousStep: add a link to go to the previous ng-walkthrough.
nextStep: add a link to go to the next ng-walkthrough.
hideNext: hide the next step link.
HiveNav: hide the navigation step links.
closeButton: true for show the button. By default false.
closeAnywhere: false for click anywhere to close. By default true.
finishButton: true for show a link to exit. By default false.
disabled: true for ignoring the walkthrough based on a boolean flag. By default false.
texts: change texts. It's an overlay of WalkthroughText.

Arrow:

showArrow: true for show the arrow. By default false.
arrowColor: change the arrow color. By default #FFF.

`ng-walkthrough-flow` attributes

All attributes are optional and not overriding the sub-components attributes except previousStep, nextStep that will be ignored.

id: HTML id.

Output events

closed: fired when a walkthrough has been closed. It sends a boolean value set to true if the walkthrough has been closed with the "finishButton" button.
finished: fired when the last walkthrough has been closed.

Focus zone:

focusHighlightAnimation: true for show highlight animation on the focus element.
focusBackdrop: true for show a dark backdrop around the focus element.
focusGlow: true for show a glow on the focus element.
radius: apply a “borderRadius” on highlight zone. If number the value as change in percent. If auto use the focused element borderRadius. If it's a simple string, use it without changes.
marginZone: add a margin of focus zone in px. (e.g. 12 15 12 13 for CSS 12px 15px 12px 13px, 12 15 for 12px 15px 12px 15px, 12 for 12px 12px 12px 12px.)
notScrollOnResize: do not scroll when resizing (e.g. may be required with dynamic menu on mobile)
observerOptions: options of DOM detection changes (default: { attributes: false, childList: true, subtree: true })

Content:

contentStyle: background style for content container. Possible values: none, darken.
rootElement: root element on which walkthrough will scroll to after each positioning, as to avoid hidden zones (facultative)

Navigation:

hidePrevious: true to hide the previous button. By default false
closeButton: true for show the button.
closeAnywhere: false for for click anywhere to close.
texts: change texts. It's a overlay of WalkthroughText.
finishButton: true for show a link to exit. By default false. Always true on the last step.

Arrow:

showArrow: true for show the arrow. By default false.
arrowColor: change the arrow color. By default #FFF.

Change texts

It's possible to change all texts. With the texts directive attribute.

WalkthroughText {
    previous = 'Previous';
    next     = 'Next';
    close    = 'Close';
}

Statics methods

WalkthroughComponent.walkthroughStop(): hide and stop the current walkthrough (impossible to open a new walkthrough). Does not work if no walkthrough is showed.
WalkthroughComponent.walkthroughContinue(): show and continue the current walkthrough. Does not work if no walkthrough is paused.
WalkthroughComponent.walkthroughHasShow(): if the a walkthrough is currently showing.
WalkthroughComponent.walkthroughNext(): to load the next walkthrough.
WalkthroughComponent.walkthroughPrevious(): to load the previous walkthrough.

Statics observable

WalkthroughComponent.onOpen: on open
WalkthroughComponent.onRefresh: on reshowing the current step
WalkthroughComponent.onClose: on close
WalkthroughComponent.onFinish: on close in the last step
WalkthroughComponent.onNavigate: on navigate
WalkthroughComponent.onNavigatePrevious: on navigate on the previous step
WalkthroughComponent.onNavigateNext: on navigate on the next step

Example

Highlighting #selectorId element with example text in ng-template.

<ng-walkthrough
    id="wt-test"
    focusElementSelector="#selectorId"
    focusBackdrop="true"
    [contentTemplate]="template"
    closeButton="true"
>
    <ng-template #template>
        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit...</p>
    </ng-template>
</ng-walkthrough>

Example of scenario with ng-walkthrough-flow:

<ng-walkthrough-flow
    #walkFlow
    id="wt-test-flow"
    focusBackdrop="true"
    focusHighlightAnimation="true"
    closeButton="true"
    closeAnywhere="false"
    showArrow="true"
    radius="auto"
    [texts]="frenchText"
>
    <ng-walkthrough
        id="wt-test1-flow"
        focusElementSelector="#test1"
        [contentText]="Lorem ipsum dolor sit amet, consectetur adipiscing elit..."
    >
    </ng-walkthrough>
    <ng-walkthrough
        id="wt-test2-flow"
        focusElementSelector="#test2"
        [contentText]="Lorem ipsum dolor sit amet, consectetur adipiscing elit..."
    >
    </ng-walkthrough>
    <ng-walkthrough
        id="wt-test3-flow"
        focusElementSelector="#test3"
        closeButton="true"
        [contentText]="Lorem ipsum dolor sit amet, consectetur adipiscing elit..."
    >
    </ng-walkthrough>
</ng-walkthrough-flow>

For more examples, see examples/example.component.html.

Publishing the library

npm run build:lib
cd dist/angular-walkthrough
npm publish

License

Like Angular, this module is released under the permissive MIT license. Your contributions are always welcome.

Harvest-Dev/ng-walkthrough