[](https://badge.fury.io/js/angular-walkthrough) [](https://www.npmjs.com/package/angular-walkthrough) [](https://raw.githubusercontent.com/harvest-dev/ng-walkthrough/master/LICENSE.md)
# Walkthrough
This Angular model is inspired in part by [ng-walkthrough](https://github.com/souly1/ng-walkthrough) for AngularJS.
## Installation
```
npm i angular-walkthrough --save
```
## Requirements
- Angular `21.0` and more
- Angular/cdk `21.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`
- For Angular 18~ use `0.11.0`
- For Angular 21 use `0.12.0` (current version)
## Demo
[See a demo](https://harvest-dev.github.io/ng-walkthrough/dist/ng-walkthrough/browser).
## 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.
```typescript
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`.
```html
Lorem ipsum dolor sit amet, consectetur adipiscing elit...
```
Example of scenario with `ng-walkthrough-flow`:
```html
```
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.