
Walkthrough
This Angular model is inspired in part by ng-walkthrough for AngularJS.
Installation
npm i angular-walkthrough --save
Requirements
- Angular
16.1
and more
- Angular/cdk
16.1
and more
Old versions:
- For Angular 6~11 use
0.8.2
- For Angular 11~15 use
0.9.8
Demo
See a demo.
Usage
ng-walkthrough
attributes
All attributes are optional.
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.
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.