{"id":13601921,"url":"https://github.com/tnicola/ngx-joyride","last_synced_at":"2025-04-12T14:56:44.677Z","repository":{"id":37828850,"uuid":"130559914","full_name":"tnicola/ngx-joyride","owner":"tnicola","description":"Angular Joyride/Tour library","archived":false,"fork":false,"pushed_at":"2023-03-06T05:04:28.000Z","size":5964,"stargazers_count":248,"open_issues_count":84,"forks_count":94,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-03T14:09:33.516Z","etag":null,"topics":["angular","angular2","demo","directive","joyride","onboarding","tour","ui-component"],"latest_commit_sha":null,"homepage":"https://tnicola.github.io/ngx-joyride/","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/tnicola.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-22T11:10:57.000Z","updated_at":"2025-04-02T04:05:03.000Z","dependencies_parsed_at":"2024-06-18T13:50:23.328Z","dependency_job_id":"8a6a7d44-72a9-4763-beed-2bffd2c78088","html_url":"https://github.com/tnicola/ngx-joyride","commit_stats":{"total_commits":322,"total_committers":19,"mean_commits":16.94736842105263,"dds":0.3074534161490683,"last_synced_commit":"d1c94fd5d9788d11cb804a4be6dacd552a3d5683"},"previous_names":["tnicola/angular2-joyride"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tnicola%2Fngx-joyride","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tnicola%2Fngx-joyride/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tnicola%2Fngx-joyride/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tnicola%2Fngx-joyride/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tnicola","download_url":"https://codeload.github.com/tnicola/ngx-joyride/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248571888,"owners_count":21126522,"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","angular2","demo","directive","joyride","onboarding","tour","ui-component"],"created_at":"2024-08-01T18:01:10.130Z","updated_at":"2025-04-12T14:56:44.660Z","avatar_url":"https://github.com/tnicola.png","language":"TypeScript","funding_links":[],"categories":["angular"],"sub_categories":[],"readme":"[![npm version](https://badge.fury.io/js/ngx-joyride.svg)](https://badge.fury.io/js/ngx-joyride)\n[![CircleCI](https://circleci.com/gh/tnicola/ngx-joyride/tree/master.svg?style=svg)](https://circleci.com/gh/tnicola/ngx-joyride/tree/master)\n[![codecov](https://codecov.io/gh/tnicola/ngx-joyride/branch/master/graph/badge.svg)](https://codecov.io/gh/tnicola/ngx-joyride)\n[![Cypress.io tests](https://img.shields.io/badge/cypress.io-tests-green.svg?style=flat-square)](https://dashboard.cypress.io/#/projects/3yary2/runs)\n\n# Angular Joyride\n\nAn Angular Tour (Joyride) library built entirely in Angular, without using any heavy external dependencies like Bootstrap or JQuery.\nFrom now on you can easily guide your users through your site showing them all the sections and features.\n\nFor Angular 2+ (2 - 13)\n\n\u003cp align=\"center\"\u003e\n\t\u003cimg src =\"https://github.com/tnicola/ngx-joyride/blob/master/docs/joyride-tour.gif\" /\u003e\n\u003c/p\u003e\n\n## Demo\n\nSee the [demo](https://tnicola.github.io/ngx-joyride/). Let's take a tour! ✈️ :earth_americas:\n\n## Install\n\n    npm install ngx-joyride --save\n\nor\n\n    yarn add ngx-joyride\n\n## Usage\n\n#### 1. Mark your HTML elements with the `joyrideStep` directive\n\n```typescript\n  \u003ch1 joyrideStep=\"firstStep\" title=\"Page Title\" text=\"Main title!\"\u003eText\u003c/h1\u003e\n  \u003cdiv joyrideStep=\"secondStep\" title=\"Page Title\" text=\"Main title!\"\u003eDiv content\u003c/div\u003e\n```\n\n#### 2. Import the `JoyrideModule` in your AppModule\n\n```typescript\n@NgModule({\n    declarations: [AppComponent],\n    imports: [JoyrideModule.forRoot(), RouterModule.forRoot([]), BrowserModule],\n    providers: [],\n    bootstrap: [AppComponent],\n})\nexport class AppModule {}\n```\n\n#### 3. Inject the `JoyrideService` in your Component and start the Tour, passing the steps order list\n\n```typescript\n@Component({\n    selector: 'app-component',\n    templateUrl: './app.component.html',\n})\nexport class AppComponent {\n    constructor(private readonly joyrideService: JoyrideService) {}\n\n    onClick() {\n        this.joyrideService.startTour(\n            { steps: ['firstStep', 'secondStep'] } // Your steps order\n        );\n    }\n}\n```\n\n#### 4. En-joy :wink:\n\n# API reference\n\n## Directive Inputs/Outputs\n\nYou can use the `joyrideStep` directive with these inputs:\n\n| @Input            | Required | Purpose                                              | Values/Type                                |\n| ----------------- | -------- | ---------------------------------------------------- | ------------------------------------------ |\n| joyrideStep       | Yes      | The step name, it should be unique.                  | string                                     |\n| stepPosition      | No       | The position in which the step will be drawn.        | 'top', 'right', 'bottom', 'left', 'center' |\n| title             | No       | The step title.                                      | string                                     |\n| text              | No       | The step text content.                               | string                                     |\n| stepContent       | No       | An Angular template with custom content.             | TemplateRef\\\u003cany\u003e                          |\n| stepContentParams | No       | Data object to pass in with Angular template         | Object                                     |\n| prevTemplate      | No       | An Angular template with a custom prev button.       | TemplateRef\\\u003cany\u003e                          |\n| nextTemplate      | No       | An Angular template with a custom next button.       | TemplateRef\\\u003cany\u003e                          |\n| doneTemplate      | No       | An Angular template with a custom done button.       | TemplateRef\\\u003cany\u003e                          |\n| counterTemplate   | No       | An Angular template with a custom counter component. | TemplateRef\\\u003cany\u003e                          |\n\n| @Output | Required | Purpose                                                                               |\n| ------- | -------- | ------------------------------------------------------------------------------------- |\n| next    | No       | It fires an event when 'Next' button is clicked.                                      |\n| prev    | No       | It fires an event when 'Prev' button is clicked.                                      |\n| done    | No       | It fires an event when 'Done' button or 'Close' are clicked and the Tour is finished. |\n\n## Options\n\n| Name                | Required | Purpose                                                                                                                                                                                                                                                                                                                                                                                        | Type     | Default value                                 |\n| ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------- |\n| steps               | Yes      | Represent the ordered list of steps name to show. e.g `steps: ['step1', 'header', 'interesting-table', 'navbar']`. This option is particularly useful for multi-pages navigation. If your step is not in the root path, you should indicate the route after the step name, with a `@` as separator. E.g. : `steps: ['firstStep', 'image@home', 'step4@about/you', 'user-avatar@user/details']` | string[] | none                                          |\n| startWith           | No       | The name of the step (plus the route for multi-page navigation) from which the stour should start.                                                                                                                                                                                                                                                                                             | string   | undefined                                     |\n| waitingTime         | No       | The time (in milliseconds) to wait before showing the next/prev step.                                                                                                                                                                                                                                                                                                                          | number   | 1                                             |\n| stepDefaultPosition | No       | Define a step default position. The stepPositon set in the directive override this value.                                                                                                                                                                                                                                                                                                      | string   | bottom                                        |\n| themeColor          | No       | Backdrop, buttons and title color. (Hexadecimal value)                                                                                                                                                                                                                                                                                                                                         | string   | #3b5560                                       |\n| showCounter         | No       | Show the counter on the bottom-left.                                                                                                                                                                                                                                                                                                                                                           | boolean  | true                                          |\n| showPrevButton      | No       | Show the \"Prev\" button.                                                                                                                                                                                                                                                                                                                                                                        | boolean  | true                                          |\n| logsEnabled         | No       | Enable logs to see info about the library status. Usuful to get a meaningful error message.                                                                                                                                                                                                                                                                                                    | boolean  | false                                         |\n| customTexts         | No       | Custom buttons text for next, prev, done buttons.                                                                                                                                                                                                                                                                                                                                              | Object   | `{ prev: 'prev', next: 'next', done: 'done'}` |\n\nYou can change each element step css overriding the default style.\n\n# How tos\n\n-   [Use Custom Content](#use-custom-content)\n-   [Use Custom Content With Dynamic Data](#use-custom-content-with-dynamic-data)\n-   [Use custom buttons and/or counter](#use-custom-buttons-and/or-counter)\n-   [Set the options](#set-the-options)\n-   [Listen for events](#listen-for-events)\n-   [Multi Pages navigation](#get-multi-pages-navigation)\n-   [Close programmatically the tour](#close-programmatically-the-tour)\n\n### Use Custom Content\n\nIf you'd like to use custom HTML content instead of simple text you can use the `stepContent` property instead of `text`. Let's see how.\n\n```html\n\u003cdiv joyrideStep=\"step1\" [stepContent]=\"customContent\"\u003e\n    I'm the target element.\n\u003c/div\u003e\n\u003cng-template #customContent\u003e\n    ... Insert whatever you'd like to ...\n\u003c/ng-template\u003e\n```\n\n### Use Custom Content With Dynamic Data\n\nIf you'd like to pass params to template, use the `stepContentParams` property. Let's see how.\n\n```html\n\u003cdiv\n    joyrideStep=\"step1\"\n    [stepContent]=\"customContent\"\n    [stepContentParams]=\"{'name': 'John'}\"\n\u003e\n    I'm the target element.\n\u003c/div\u003e\n\u003cng-template #customContent let-person=\"name\"\u003e Hello {{person}} \u003c/ng-template\u003e\n```\n\n### Use custom buttons and/or counter\n\n#### Custom buttons texts\n\nIf you'd like to customize the next, prev and done texts, you can use the `customTexts` option:\n\n```typescript\nthis.joyrideService.startTour({\n  ...\n  customTexts: {\n    next: '\u003e\u003e',\n    prev: '\u003c\u003c',\n    done: 'Ok'\n  }\n});\n```\n\n#### Custom buttons templates\n\nIf you'd like to customize the next, prev and done button or you want to use your own counter component, you can:\n\n**Important**: These inputs should be used just once, in the first step of your tour.\n\n```html\n\u003cdiv\n    joyrideStep=\"step1\"\n    [prevTemplate]=\"prevButton\"\n    [nextTemplate]=\"nextButton\"\n    [doneTemplate]=\"doneButton\"\n    [counterTemplate]=\"counter\"\n\u003e\n    I'm the target element.\n\u003c/div\u003e\n\u003cng-template #prevButton\u003e\n    \u003cmy-button\u003eGo back!\u003c/my-button\u003e\n\u003c/ng-template\u003e\n\u003cng-template #nextButton\u003e\n    \u003cmy-button\u003eGo ahead!\u003c/my-button\u003e\n\u003c/ng-template\u003e\n\u003cng-template #doneButton\u003e\n    \u003cmy-button\u003eComplete\u003c/my-button\u003e\n\u003c/ng-template\u003e\n\u003cng-template #counter let-step=\"step\" let-total=\"total\"\u003e\n    {{ step }} of {{ total }} steps\n\u003c/ng-template\u003e\n```\n\nN.B.: The counter template has 2 parameters, `step` represents the current step number, `total` is the total number of steps.\n\n### Set the options\n\n```typescript\nthis.joyrideService.startTour({\n    steps: ['step1', 'my-step@home', 'lastStep@home'],\n    showPrevButton: false,\n    stepDefaultPosition: 'top',\n    themeColor: '#212f23',\n});\n```\n\n### Listen for events\n\n**Mode 1: Using directive output events**\n\n```typescript\n@Component({\n    selector: 'app-component',\n    template: `\n        \u003cdiv\n            joyrideStep=\"joy1\"\n            title=\"title\"\n            (prev)=\"onPrev()\"\n            (next)=\"onNext()\"\n        \u003e\n            Hello!\n        \u003c/div\u003e\n        \u003cdiv joyrideStep=\"joy2\" title=\"title2\" (done)=\"onDone()\"\u003eHello!\u003c/div\u003e\n    `,\n})\nexport class AppComponent {\n    constructor(private readonly joyrideService: JoyrideService) {}\n\n    onClick() {\n        this.joyrideService.startTour(\n            { steps: ['joy1', 'joy2'] } // Your steps order\n        );\n    }\n\n    onNext() {\n        // Do something\n    }\n\n    onPrev() {\n        // Do something\n    }\n\n    onDone() {\n        // Do something\n    }\n}\n```\n\n**Mode 2: Subscribing to startTour**\n\n```typescript\n@Component({\n    selector: 'app-component',\n    template: `\n        \u003cdiv\n            joyrideStep=\"joy1\"\n            title=\"title\"\n            (prev)=\"onPrev()\"\n            (next)=\"onNext()\"\n        \u003e\n            Hello!\n        \u003c/div\u003e\n        \u003cdiv joyrideStep=\"joy2\" title=\"title2\" (done)=\"onDone()\"\u003eHello!\u003c/div\u003e\n    `,\n})\nexport class AppComponent {\n    constructor(private readonly joyrideService: JoyrideService) {}\n\n    onClick() {\n        this.joyrideService.startTour({ steps: ['joy1', 'joy2'] }).subscribe(\n            (step) =\u003e {\n                /*Do something*/\n            },\n            (error) =\u003e {\n                /*handle error*/\n            },\n            () =\u003e {\n                /*Tour is finished here, do something*/\n            }\n        );\n    }\n}\n```\n\nN.B.: Using events is very helpful when your next target is hidden in the DOM. If a target is not visible (e.g. \\*ngIf='false') you should use the (next) event to make the target somehow findable in the DOM.\n\n### Get Multi Pages navigation\n\nIf your steps are scattered among different pages you can now reach them, just add their name in the `steps` list followed by `@route/to/page`.\n\nLets suppose you have three steps:\n\n-   navbar, located in the app root /\n-   user-avatar, located in /user/details\n-   info, located in /about\n\nWhat you should do is adding your steps in this way:\n\n```typescript\n...\n    this.joyrideService.startTour({steps: [\"navbar\", \"user-avatar@user/details\", \"info@about\"]});\n...\n```\n\n**NB**: If you're using lazy modules, you should import the JoyrideModule in your AppModule using `JoyrideModule.forRoot()`. In your lazy loaded feature modules use `JoyrideModule.forChild()` instead.\n\n### Close programmatically the tour\n\nIn order to close programmatically the tour you'll just need to call the JoyrideService `closeTour()` method:\n\n```typescript\n...\n    this.joyrideService.closeTour();\n...\n```\n\n## Licence\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftnicola%2Fngx-joyride","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftnicola%2Fngx-joyride","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftnicola%2Fngx-joyride/lists"}