{"id":23021090,"url":"https://github.com/p1n2o/ng-tour","last_synced_at":"2026-05-15T18:32:20.628Z","repository":{"id":57134735,"uuid":"277811967","full_name":"P1N2O/ng-tour","owner":"P1N2O","description":"A simple, minimalistic tour/on-boarding library for Angular (2+)","archived":false,"fork":false,"pushed_at":"2020-07-07T13:07:27.000Z","size":22,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-09T01:47:09.138Z","etag":null,"topics":["angular","ng-tour","on-boarding","tour","ui-guide","walk-through"],"latest_commit_sha":null,"homepage":"https://github.com/P1N2O/ng-tour","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/P1N2O.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-07-07T12:35:53.000Z","updated_at":"2023-12-09T22:08:59.000Z","dependencies_parsed_at":"2022-09-04T15:52:06.542Z","dependency_job_id":null,"html_url":"https://github.com/P1N2O/ng-tour","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/P1N2O%2Fng-tour","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/P1N2O%2Fng-tour/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/P1N2O%2Fng-tour/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/P1N2O%2Fng-tour/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/P1N2O","download_url":"https://codeload.github.com/P1N2O/ng-tour/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246871449,"owners_count":20847480,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["angular","ng-tour","on-boarding","tour","ui-guide","walk-through"],"created_at":"2024-12-15T12:16:21.593Z","updated_at":"2025-10-27T12:04:55.615Z","avatar_url":"https://github.com/P1N2O.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ng-tour\n\nA simple, minimalistic tour/on-boarding library for Angular (2+).\n\n**Support: Angular 2+ (2, 4, 5, 6, 7, 8, 9, 10)**\n\n## Installation\n\n    npm install --save @p1n2o/ng-tour\n\n## Usage\n\n1. Import the AngularTourModule \u0026 RouterModule in your AppModule:\n\n```\nimport { RouterModule } from \"@angular/router\";\nimport { AngularTourModule } from \"@p1n2o/ng-tour\";\n\n@NgModule({\n    declarations: [AppComponent],\n    imports: [\n            RouterModule.forRoot([]),\n            AngularTourModule.forRoot(),\n            BrowserModule\n    ],\n    providers: [],\n    bootstrap: [AppComponent]\n    })\nexport class AppModule { }\n```\n\n2. Import the AngularTourModule in your Feature Modules:\n\n```\n    @NgModule({\n        declarations: [FeatureComponent],\n        imports: [\n            AngularTourModule.forChild()\n        ],\n        providers: [],\n        })\n    export class FeatureModule { }\n```\n\n3. Use **ngTourInit** directive inside **app.component.html**. A good choice is marking `\u003crouter-outlet\u003e` with it.\n\n```\n    \u003croute-outlet ngTourInit\u003e\u003c/route-outlet\u003e\n```\n\n5. Mark your target HTML elements with the **ngTour** directive with a unique name.\n\n```\n    \u003cdiv ngTour=\"sampleElem1\"\u003e...\u003c/div\u003e\n    \u003cspan ngTour=\"sampleElem2\"\u003e...\u003c/span\u003e\n```\n\n5. Inject NgTourService in your Component (where Tour is being started).\n\n```import {TourService, Tour, StepOptions, TourEvents} from 'ng-tour';\n\n    @Component({\n        selector: 'component-of-your-choice',\n        templateUrl: './your.component.html'\n    })\n    export class ComponentOfYourChoice {\n        constructor(private readonly tourService: TourService) { }\n    }\n```\n\n6. Create a configuration object and pass it as an argument to the startTour method\n\n```\nconst tour: Tour = {\n    steps: [\n        {\n            stepName: \"sampleElem1\",\n            route: \"first-route\",\n            title: 'My first lazily loaded title',\n            description: \"My first feature description\",\n        },\n        {\n            stepName: \"sampleElem2\",\n            route: \"second-route\",\n            title: \"My second lazily loaded title\",\n            description: \"My second feature description\",\n            options:{placement: 'top', smoothScroll: true}\n        }\n    ],\n    tourOptions: {\n        backdrop: true,\n        placement: 'bottom',\n    }\n}\n```\n\n**Keep in mind if you implement your own Step template, you can use your own Step properties besides required ('stepName' and 'route')**\n\n```\nngOnInit() {\n    this.tourService.startTour(this.tour);\n}\n```\n\nor\n\n```\nstartTour() {\n    this.tourService.startTour(this.tour);\n}\n```\n\n### Customization\n\nIf you want to use tour own Step template wrap it with `\u003cng-tour-template\u003e` and place in **app.component.html**. Mark the provided template with reference with assigned value 'step\\$' that gives you access to steps Stream. To handle controls event you could use tourEvent directive with corresponded input value (one of 'next', 'prev', 'close')\n\n```\n\u003cng-tour-template #refToExportAs=\"steps$\"\u003e\n    \u003cdiv  class=\"tour-step-modal__content\" *ngIf=\"refToExportAs.steps$ | async as step\"\u003e\n        \u003cdiv \u003e\n            \u003cdiv class=\"tour-step-modal__header\"\u003e\n                \u003ch3 class=\"tour-step-modal__title\"\u003e\n                    {{step.title}}\n                \u003c/h3\u003e\n                \u003cbutton\n                    class=\"tour-btn-close\"\n                    type=\"button\"\n                    stepEvent=\"close\"\n                    (break)=\"onBreak($event)\" // add this line if you want to handle the event is emitted after a corresponded user action. Of cause, the handler's name is up to you.\n                    (done)=\"onDone($event)\" // to handle the event is emitted after a corresponded user action\n                \u003e\n                    \u0026times;\n                \u003c/button\u003e\n            \u003c/div\u003e\n            \u003cdiv class=\"tour-step-modal__body\"\u003e\n                \u003cp class=\"tour-step-modal__description\"\u003e\n                    {{step.description}}\n                \u003c/p\u003e\n                \u003cp class=\"tour-step-modal__adds\"\u003e\n                    {{step.customData}}\n                \u003c/p\u003e\n            \u003c/div\u003e\n            \u003cdiv class=\"tour-step-modal__footer\"\u003e\n                \u003cdiv *ngIf=\"!step.options.withoutCounter\" class=\"tour-step-modal__counter\"\u003e\n                    {{step.index + 1}} {{step.ctrlBtns.of} {{step.total}}\n                \u003c/div\u003e\n                \u003cbutton\n                    *ngIf=\"!step.options.withoutPrev \u0026\u0026 step.index\"\n                    type=\"button\"\n                    class=\"tour-btn\"\n                    stepEvent=\"prev\"\n                    (prev)=\"onPrev($event)\" // to handle the event is emitted after a corresponded user action\n                \u003e\n                    {{step.ctrlBtns.prev}}\n                \u003c/button\u003e\n                \u003cbutton\n                    *ngIf=\"step.index + 1 !== step.total\"\n                    type=\"button\"\n                    class=\"tour-btn tour-btn-next\"\n                    stepEvent=\"next\"\n                    (next)=\"onNext($event)\" // to handle the event is emitted after a corresponded user action\n                \u003e\n                    {{step.ctrlBtns.next}}\n                \u003c/button\u003e\n                \u003cbutton\n                    *ngIf=\"step.index + 1 === step.total\"\n                    type=\"button\"\n                    class=\"tour-btn tour-btn-done\"\n                    stepEvent=\"close\"\n                    (done)=\"onDone($event)\" // to handle the event is emitted after a corresponded user action\n                \u003e\n                    {{step.ctrlBtns.done}}\n                \u003c/button\u003e\n            \u003c/div\u003e\n        \u003c/div\u003e\n    \u003c/div\u003e\n\u003c/ng-tour-template\u003e\n```\n\nKeep in mind if you use **`\u003cng-tour-template\u003e`** and **`ngTourInit`** at the same time 'customTemplate' option is set to true programmatically. If you omit **`ngTourInit`** and want to use your own Step template set this option to true manually.\n\n### Internalization\n\nIf you implement a custom Step template you can implement any Internalization you want, but if you use the provided Step template you can not do so. There is an embedded one for this case.\n\nYou can pass an object with the required translations to the Step properties the title and the description.\n\n```\ntitle: {\n    'en-EN': 'My first feature',\n    'ru-RU': 'Моя первая фича',\n    'fr-FR': 'Mon premier caractéristique',\n}\n```\n\nYou also can define t he required translations for the Step controls. Simply pass the corresponded object to the Tour option ctrlBtns. There is default value below.\n\n```\ndefaultTranslation {\n    done: {\n        'en-EN': 'done',\n        'ru-RU': 'закр',\n        'fr-FR': 'fini',\n    },\n    prev: {\n        'en-EN': 'prev',\n        'ru-RU': 'пред',\n        'fr-FR': 'préc'\n    },\n    next: {\n        'en-EN': 'next',\n        'ru-RU': 'след',\n        'fr-FR': 'proch',\n    },\n    of: {\n        'en-EN': 'of',\n        'ru-RU': \"из\",\n        'fr-FR': 'de',\n    }\n}\n```\n\n## API reference\n\n### Tour Properties\n\nTour configuration object contains steps array and could include common options, event handlers and set of control button names\n\n| Name       | Required | Type       | Destination                                                                                |\n| ---------- | -------- | ---------- | ------------------------------------------------------------------------------------------ |\n| steps      | yes      | TourStep[] | This option define Tour Steps and its order                                                |\n| tourEvents | no       | TourEvents | define event handlers for 'tour start', 'tour break', 'tour end', 'next step', 'prev step' |\n| tourOption | no       | TourStep   | Set common options. Could be redefined with Step options                                   |\n| ctrlBtns   | no       | CtrlBtns   | Set translations of the control buttons for any languages you want                         |\n\n#### Tour Events\n\nThese events are functions witch is called within corresponded tourService methods. You can pass your own implementation of these functions within tourEvent property for example to collect some statistical data about user behavior. Keep in mind Tour Events unlike Step Events could fire without user activity in case continueIfTargetAbsent property is set to true (default value).\n\n| Name      | Required | Props                                                  | Description                                                                                   |\n| --------- | -------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------- |\n| tourStart | no       | {tourEvent: string, tour?: Tour}                       | Add logic executed before the Tour will be started                                            |\n| tourBreak | no       | {tourEvent: string, step?: number, history?: number[]} | Add logic executing before the Tour will be stoped untimely                                   |\n| tourEnd   | no       | {tourEvent: string, step?: number, history?: number[]} | Add logic executing before the Tour will be stopped after finishing (latest step was visited) |\n| next      | no       | {tourEvent: string, step?: number, history?: number[]} | Add logic executing before the next step will be initiated                                    |\n| prev      | no       | {tourEvent: string, step?: number, history?: number[]} | Add logic executing before the previous step will be initiated                                |\n\n### Step Properties\n\n| Name                   | Required | Type        | Destination                                                                                                                                                                                           | Default value                 |\n| ---------------------- | -------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |\n| stepName               | yes      | string      | Define unique name of the Step                                                                                                                                                                        |\n| route                  | yes      | string      | Define route corresponded to the Step                                                                                                                                                                 |\n| index                  | no       | number      | 'Index' value is set by TourService service according to the position of the Step in the Steps array                                                                                                  |\n| title                  | no       | string      | Set title of the current Step                                                                                                                                                                         | \"\"                            |\n| description            | no       | string      | Set description of the current Step                                                                                                                                                                   | \"\"                            |\n| ctrlBtns               | no       | CtrlBtns    | Set translations of the control buttons for any languages you want                                                                                                                                    | [see below](#defaultCtrlBtns) |\n| options                | no       | StepOptions | To customize separate Step                                                                                                                                                                            | described below               |\n| options:               |          |             |                                                                                                                                                                                                       |\n| className              | no       | string      | Set custom class to the Step component                                                                                                                                                                | \"\"                            |\n| themeColor             | no       | string      | Define theme color                                                                                                                                                                                    | 'rgb(20, 60, 60)'             |\n| backdrop               | no       | boolean     | Add backdrop if option set true                                                                                                                                                                       | true                          |\n| opacity                | no       | number      | Define the backdrop opacity                                                                                                                                                                           | .6                            |\n| placement              | no       | string      | This option define position of step modal relative to target. Possible values: 'down', 'top', 'left', 'right', 'center', 'right-center', 'left-center', right-top', 'left-top' **( case no matter )** | \"Down\"                        |\n| customTemplate         | no       | boolean     | This option has by default value true if you used `\u003cng-tour-template\u003e` and directive **ngTourInit** simultaneously, otherwise false.                                                                  | true/false                    |\n| withoutCounter         | no       | boolean     | If true remove counter including a number of the step and total number of steps from the Step template                                                                                                | false                         |\n| withoutPrev            | no       | boolean     | If true remove 'Prev' control button from the Step template                                                                                                                                           | false                         |\n| arrowToTarget          | no       | boolean     | If true add arrow in direction corresponded location of the Step target                                                                                                                               | true                          |\n| scrollTo               | no       | boolean     | If value equals true, the window is scrolled to show Step target and modal (popup)                                                                                                                    | true                          |\n| scrollSmooth           | no       | boolean     | If true option behavior of the window scroll is set to smooth                                                                                                                                         | false                         |\n| continueIfTargetAbsent | no       | boolean     | If true and the Step target is absent will initialize the next Step                                                                                                                                   | true                          |\n| animatedStep           | no       | boolean     | If true add classes to control css animation                                                                                                                                                          | true                          |\n| fixed                  | no       | boolean     | If value equals true position css property of the Step Component and Backdrop Component is set to the 'fixed', otherwise 'absolute'                                                                   | false                         |\n| animationDelay         | no       | number      | Required in case of routing with lazy loaded Feature Modules. Delay defined in ms                                                                                                                     | 500                           |\n| stepTargetResize       | no       | number[]    | Change size in px of the Step target window. Number with index 0 define Width. Number with index 1 if exist define Height differ from the Width                                                       | [0]                           |\n| minWidth               | no       | string      | Define min-width of the Step modal                                                                                                                                                                    | '200px'                       |\n| minHeight              | no       | string      | Define min-height of the Step modal                                                                                                                                                                   | '200px'                       |\n| maxWidth               | no       | string      | Define max-width of the Step modal                                                                                                                                                                    | '400px'                       |\n| maxHeight              | no       | string      | Define max-height of the Step modal                                                                                                                                                                   | '400px'                       |\n| autofocus              | no       | boolean     | If true 'next' and 'done' buttons obtain focus                                                                                                                                                        | true                          |\n| closeOnClickOutside    | no       | boolean     | If true any click outside step modal will cause closing the Tour. This is maybe useful if you set backdrop options to false and user have access to your site controls (for example navigation menu)  | false                         |\n\n### Services\n\n#### TourService methods:\n\n| Name           | Args       | Description                                                                         | Return                    |\n| -------------- | ---------- | ----------------------------------------------------------------------------------- | ------------------------- |\n| main:          |            |                                                                                     |\n| startTour      | tour: Tour | start Tour (The only necessary to use this lib)                                     | void                      |\n| prevStep       |            | Call initStep with previous stepName                                                | void                      |\n| nextStep       |            | Call initStep with next stepName                                                    | void                      |\n| stopTour       |            | stop Tour                                                                           | void                      |\n| additional:    |            |                                                                                     |\n| getStepsStream |            | Return the steps observable                                                         | steps\\$                   |\n| resetStep      | string     | number, TourStep                                                                    | Change Step configuration | void |\n| getHistory     |            | return array of the indexes of the passed Steps                                     | stepIndexes[]             |\n| getStepByName  | string     | return the Step with the given stepName                                             | TourStep                  |\n| getStepByIndex | number     | return the Step with the given index                                                | TourStep                  |\n| getLastStep    |            | return the last initialized Step                                                    | TourStep                  |\n| isRouteChanged |            | return true if the route property of the current Step differs from the previous one | boolean                   |\n| getTourStatus  |            | return true if Tour started                                                         | boolean                   |\n\n### Directives\n\n#### ngTourInit\n\nThis directive is similar to a structural one if it is used solo without `\u003cng-tour-template\u003e`. In this case, **`ngTourInit`** adds provided `Step template` to the DOM after the Tour is started and removes it after the Tour is stoped. If **`ngTourInit`** is used along with **`\u003cng-tour-template\u003e`** (no matter which element was marked with directive **`\u003cng-tour-template\u003e`** or some other) it make only one thing it set 'customTemplate' property to true.\n\n#### ngTour\n\nThis directive is required to mark Step target\n\n| @Input | Required | Description                       | Values/Type |\n| ------ | -------- | --------------------------------- | ----------- |\n| ngTour | yes      | The value should be unique string | string      |\n\n#### stepEvent\n\nThis directive binds listeners (with corresponded Tour methods) to Step's controls and emits corresponded events. It may come in handy if you want **to master your own Step template**.\n\n| @Input    | Required | Destination                                                                                                              |\n| --------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |\n| stepEvent | required | Possible values are 'next' , 'prev' and 'close'. Value predefines which handler will be implemented for the click event. |\n\n| @Output | Props                                                | Destination                                                                            |\n| ------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------- |\n| next    | {tourEvent: string, step: number, history: number[]} | Emit 'next' event with described props. The destination is the same as tourEvents have |\n| prev    | {tourEvent: string, step: number, history number[]}  | Emit 'prev' event with described props.                                                |\n| break   | {tourEvent: string, step: number, history: number[]} | Emit 'break' event with described props.                                               |\n| done    | {tourEvent: string, step: number, history: number[]} | Emit 'done' event with described props.                                                |\n\n### Components\n\n#### ng-tour-template\n\n| Output | Props                                                | Description                                                                            |\n| ------ | ---------------------------------------------------- | -------------------------------------------------------------------------------------- |\n| next   | {tourEvent: string, step: number, history: number[]} | Emit 'next' event with described props. The destination is the same as tourEvents have |\n| prev   | {tourEvent: string, step: number, history: number[]} | Emit 'prev' event with described props.                                                |\n| break  | {tourEvent: string, step: number, history: number[]} | Emit 'break' event with described props.                                               |\n| done   | {tourEvent: string, step: number, history: number[]} | Emit 'done' event with described props.                                                |\n\n### SCSS Customizing\n\nYou can easily redefine styles of the provided Step template in any scss files importing in style.scss file of your project.\n\n#### Main selectors\n\n| Name                            | Select                                                                      |\n| ------------------------------- | --------------------------------------------------------------------------- |\n| .tour-step-modal                | Step (includes provided template and custom template)                       |\n| .tour-step-modal\\_\\_content     | provided Step template                                                      |\n| .tour-step-modal\\_\\_header      | provided Step header (includes title and Close control)                     |\n| .tour-btn-close                 | Close control                                                               |\n| .tour-step-modal\\_\\_title       | provided Step title                                                         |\n| .tour-step-modal\\_\\_body        | provided Step body (includes Step description)                              |\n| .tour-step-modal\\_\\_description | provided Step description                                                   |\n| .tour-step-modal\\_\\_footer      | provided Step footer (includes Step controls Next, Prev, Done, and Counter) |\n| .tour-step-modal\\_\\_counter     | Counter                                                                     |\n| .tour-btn-next                  | Next control                                                                |\n| .tour-btn-prev                  | Prev control                                                                |\n| .tour-btn-done                  | Done control                                                                |\n| .tour-btn                       | Common selector for Step footer controls                                    |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fp1n2o%2Fng-tour","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fp1n2o%2Fng-tour","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fp1n2o%2Fng-tour/lists"}