Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

@termex21/ngx-joyride

Package Overview
Dependencies
Maintainers
1
Versions
2
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@termex21/ngx-joyride

An Angular Tour (Joyride) library built entirely in Angular, without using any heavy external dependencies like Bootstrap or JQuery. From now on you can easily guide your users through your site showing them all the sections and features.

  • 2.5.1
  • latest
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
1
Maintainers
1
Weekly downloads
 
Created
Source

npm version CircleCI codecov Cypress.io tests

Angular Joyride

An Angular Tour (Joyride) library built entirely in Angular, without using any heavy external dependencies like Bootstrap or JQuery. From now on you can easily guide your users through your site showing them all the sections and features.

For Angular 2+ (2 - 13)

Demo

See the demo. Let's take a tour! ✈️ :earth_americas:

Install

npm install ngx-joyride --save

or

yarn add ngx-joyride

Usage

1. Mark your HTML elements with the joyrideStep directive
  <h1 joyrideStep="firstStep" title="Page Title" text="Main title!">Text</h1>
  <div joyrideStep="secondStep" title="Page Title" text="Main title!">Div content</div>
2. Import the JoyrideModule in your AppModule
@NgModule({
    declarations: [AppComponent],
    imports: [JoyrideModule.forRoot(), RouterModule.forRoot([]), BrowserModule],
    providers: [],
    bootstrap: [AppComponent],
})
export class AppModule {}
3. Inject the JoyrideService in your Component and start the Tour, passing the steps order list
@Component({
    selector: 'app-component',
    templateUrl: './app.component.html',
})
export class AppComponent {
    constructor(private readonly joyrideService: JoyrideService) {}

    onClick() {
        this.joyrideService.startTour(
            { steps: ['firstStep', 'secondStep'] } // Your steps order
        );
    }
}
4. En-joy :wink:

API reference

Directive Inputs/Outputs

You can use the joyrideStep directive with these inputs:

@InputRequiredPurposeValues/Type
joyrideStepYesThe step name, it should be unique.string
stepPositionNoThe position in which the step will be drawn.'top', 'right', 'bottom', 'left', 'center'
titleNoThe step title.string
textNoThe step text content.string
stepContentNoAn Angular template with custom content.TemplateRef<any>
stepContentParamsNoData object to pass in with Angular templateObject
prevTemplateNoAn Angular template with a custom prev button.TemplateRef<any>
nextTemplateNoAn Angular template with a custom next button.TemplateRef<any>
doneTemplateNoAn Angular template with a custom done button.TemplateRef<any>
counterTemplateNoAn Angular template with a custom counter component.TemplateRef<any>
@OutputRequiredPurpose
nextNoIt fires an event when 'Next' button is clicked.
prevNoIt fires an event when 'Prev' button is clicked.
doneNoIt fires an event when 'Done' button or 'Close' are clicked and the Tour is finished.

Options

NameRequiredPurposeTypeDefault value
stepsYesRepresent 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
startWithNoThe name of the step (plus the route for multi-page navigation) from which the stour should start.stringundefined
waitingTimeNoThe time (in milliseconds) to wait before showing the next/prev step.number1
stepDefaultPositionNoDefine a step default position. The stepPositon set in the directive override this value.stringbottom
themeColorNoBackdrop, buttons and title color. (Hexadecimal value)string#3b5560
showCounterNoShow the counter on the bottom-left.booleantrue
showPrevButtonNoShow the "Prev" button.booleantrue
logsEnabledNoEnable logs to see info about the library status. Usuful to get a meaningful error message.booleanfalse
customTextsNoCustom buttons text for next, prev, done buttons.Object{ prev: 'prev', next: 'next', done: 'done'}

You can change each element step css overriding the default style.

How tos

Use Custom Content

If 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.

<div joyrideStep="step1" [stepContent]="customContent">
    I'm the target element.
</div>
<ng-template #customContent>
    ... Insert whatever you'd like to ...
</ng-template>

Use Custom Content With Dynamic Data

If you'd like to pass params to template, use the stepContentParams property. Let's see how.

<div
    joyrideStep="step1"
    [stepContent]="customContent"
    [stepContentParams]="{'name': 'John'}"
>
    I'm the target element.
</div>
<ng-template #customContent let-person="name"> Hello {{person}} </ng-template>

Use custom buttons and/or counter

Custom buttons texts

If you'd like to customize the next, prev and done texts, you can use the customTexts option:

this.joyrideService.startTour({
  ...
  customTexts: {
    next: '>>',
    prev: '<<',
    done: 'Ok'
  }
});
Custom buttons templates

If you'd like to customize the next, prev and done button or you want to use your own counter component, you can:

Important: These inputs should be used just once, in the first step of your tour.

<div
    joyrideStep="step1"
    [prevTemplate]="prevButton"
    [nextTemplate]="nextButton"
    [doneTemplate]="doneButton"
    [counterTemplate]="counter"
>
    I'm the target element.
</div>
<ng-template #prevButton>
    <my-button>Go back!</my-button>
</ng-template>
<ng-template #nextButton>
    <my-button>Go ahead!</my-button>
</ng-template>
<ng-template #doneButton>
    <my-button>Complete</my-button>
</ng-template>
<ng-template #counter let-step="step" let-total="total">
    {{ step }} of {{ total }} steps
</ng-template>

N.B.: The counter template has 2 parameters, step represents the current step number, total is the total number of steps.

Set the options

this.joyrideService.startTour({
    steps: ['step1', 'my-step@home', 'lastStep@home'],
    showPrevButton: false,
    stepDefaultPosition: 'top',
    themeColor: '#212f23',
});

Listen for events

Mode 1: Using directive output events

@Component({
    selector: 'app-component',
    template: `
        <div
            joyrideStep="joy1"
            title="title"
            (prev)="onPrev()"
            (next)="onNext()"
        >
            Hello!
        </div>
        <div joyrideStep="joy2" title="title2" (done)="onDone()">Hello!</div>
    `,
})
export class AppComponent {
    constructor(private readonly joyrideService: JoyrideService) {}

    onClick() {
        this.joyrideService.startTour(
            { steps: ['joy1', 'joy2'] } // Your steps order
        );
    }

    onNext() {
        // Do something
    }

    onPrev() {
        // Do something
    }

    onDone() {
        // Do something
    }
}

Mode 2: Subscribing to startTour

@Component({
    selector: 'app-component',
    template: `
        <div
            joyrideStep="joy1"
            title="title"
            (prev)="onPrev()"
            (next)="onNext()"
        >
            Hello!
        </div>
        <div joyrideStep="joy2" title="title2" (done)="onDone()">Hello!</div>
    `,
})
export class AppComponent {
    constructor(private readonly joyrideService: JoyrideService) {}

    onClick() {
        this.joyrideService.startTour({ steps: ['joy1', 'joy2'] }).subscribe(
            (step) => {
                /*Do something*/
            },
            (error) => {
                /*handle error*/
            },
            () => {
                /*Tour is finished here, do something*/
            }
        );
    }
}

N.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.

Get Multi Pages navigation

If 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.

Lets suppose you have three steps:

  • navbar, located in the app root /
  • user-avatar, located in /user/details
  • info, located in /about

What you should do is adding your steps in this way:

...
    this.joyrideService.startTour({steps: ["navbar", "user-avatar@user/details", "info@about"]});
...

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.

Close programmatically the tour

In order to close programmatically the tour you'll just need to call the JoyrideService closeTour() method:

...
    this.joyrideService.closeTour();
...

Licence

MIT

Keywords

FAQs

Package last updated on 04 Dec 2022

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc