Neurosis Prevention Mechanism

    toppy
    TypeScript icon, indicating that this package has built-in type declarations

    2.3.4 • Public • Published


    Toppy

    Tiny Angular library to create overlays for tooltips, modals, dropdowns, alerts, toastr, popovers, menus, and more

    Github Release Licence Downloads


    Demo and documentation

    Installation

    step 1: Install from npm or yarn

    npm install toppy // or
    yarn add toppy

    step 2: Import ToppyModule in your main module

    import { ToppyModule } from 'toppy';
     
    @NgModule({
      declarations: [AppComponent],
      imports: [BrowserModule, ToppyModule], // <==
      bootstrap: [AppComponent]
    })
    export class AppModule {}

    step 3: Import Toppy service in your component

    import { Toppy } from 'toppy'; // <==
     
    @Component({
      selector: 'app-root',
      template: '<div #el>Click me</div>'
    })
    export class AppComponent {
      @ViewChild('el', { read: ElementRef })
      el: ElementRef;
     
      constructor(private _toppy: Toppy) {}
     
      ngOnInit() {
        const position = new RelativePosition({
          placement: OutsidePlacement.BOTTOM_LEFT,
          src: this.el.nativeElement
        });
     
        this.overlay = this._toppy
          .position(position)
          .content('hello') // content
          .create();
      }
     
      open() {
        this.overlay.open();
      }
     
      close() {
        this.overlay.close();
      }
    }

    Content

    Toppy allows to use string, html, TemplateRef, Component as overlay content.

    Plain text

    this.overlay = this._toppy
      .position(position)
      .content(`some plain text content`) // simple text
      .create();

    HTML content

    this.overlay = this._toppy
      .position(position)
      .content(`<div>any HTML content</div>`, { hasHTML: true }) // html
      .create();

    Using TemplateRef

    <ng-template #tpl>Hello world!</ng-template>
    @ViewChild('tpl') tpl:TemplateRef<any>;
     
    this.overlay = this._toppy
      .position(position)
      .content(this.tpl) // template ref
      .create();

    Component

    // host component
    @Component({
      template: '<div>Hello</div>'
    })
    export class HelloComponent {}
    this.overlay = this._toppy
      .position(position)
      .content(HelloComponent) // <==
      .create();

    Dont forget to add host component in entryComponents in module

    Positions

    Position determines the location and size of the overlay. There are four positions:

    Relative position

    Overlay position that is relative to specific element. These are used in tooltips, popovers, dropdowns, menus

    new RelativePosition({
      src: HTMLElement, // target element
      placement: OutsidePlacement, // location of the content
      width: string | number, // content width eg, `auto`, 150, `30%`
      height: string | number, // content height eg, `auto`, 150, `30%`
      autoUpdate: boolean // update position when window scroll/resize/drag
    });

    Relative position supports 12 placements:

    OutsidePlacement.BOTTOM;
    OutsidePlacement.BOTTOM_LEFT;
    OutsidePlacement.BOTTOM_RIGHT;
    OutsidePlacement.LEFT;
    OutsidePlacement.LEFT_BOTTOM;
    OutsidePlacement.LEFT_TOP;
    OutsidePlacement.RIGHT;
    OutsidePlacement.RIGHT_BOTTOM;
    OutsidePlacement.RIGHT_TOP;
    OutsidePlacement.TOP;
    OutsidePlacement.TOP_LEFT;
    OutsidePlacement.TOP_RIGHT;

    Global position

    Overlay position that is relative to window viewport. These are used in modals, alerts, toastr

    new GlobalPosition({
      placement: InsidePlacement, // location of the content.
      width: string | number, // content width eg, `auto`, `150`, `30%`
      height: string | number, //content height eg, `auto`, 150, `30%`
      offset: number // oustide space of the content, in px
    });

    Global position supports 9 placements:

    InsidePlacement.BOTTOM;
    InsidePlacement.BOTTOM_LEFT;
    InsidePlacement.BOTTOM_RIGHT;
    InsidePlacement.LEFT;
    InsidePlacement.RIGHT;
    InsidePlacement.TOP;
    InsidePlacement.TOP_LEFT;
    InsidePlacement.TOP_RIGHT;
    InsidePlacement.CENTER;

    Slide position

    Overlay position that is relative to window viewport. These are used in side panels, sidebars, blade

    new SlidePosition({
      placement: SlidePlacement, // rigth or left
      width: string // width eg, '300px' or '30%'
    });

    Slide position supports 2 placements:

    SlidePlacement.LEFT;
    SlidePlacement.RIGHT;

    Fullscreen position

    Overlay that occupies complete size of the viewport.

    new FullScreenPosition();

    Configuration

    this.toppy
      .position(positionToppyPosition)
      .config(configurationToppyConfig = {})
      .content('hello')
      .create();
    property for
    backdrop boolean · whether to show backdrop layer · default: false
    closeOnEsc boolean · clicking Escape button will close overlay · default: false
    closeOnDocClick boolean · dismiss on clicking outside of content · default: false
    listenWindowEvents boolean · auto adjust the position on scroll/resize · default: true
    containerClass string · overlay container class name · default: t-overlay
    wrapperClass string · overlay wrapper class name · default: ''
    backdropClass string · overlay backdrop class name · default: ''
    bodyClass string · body class when overlay is open · default: t-open
    windowResizeCallback function · triggered on window scroll
    docClickCallback function · triggered on document click

    Component communication

    Component Data

    When you host a component, you can control the overlay through ToppyOverlay service. Using this service you can access all properties that is provided in content. Also the properties comes with close.

    this.overlay = this._toppy
      .position(position)
      .content(HelloComponent, { propName: 'toppy-test-prop' })
      .create();
     
    this.overlay.listen('t_compins').subscribe(comp => {
      console.log('component is ready!', comp); // returns HelloComponent
    });
    // host component
    @Component({
      template: '<div>Some text</div>'
    })
    export class HelloComponent {
      constructor(public overlay: ToppyOverlay) {
        console.log(this.overlay.props.propName); // will return 'toppy-test-prop'
      }
     
      close() {
        this.overlay.close();
      }
    }

    Template Data

    This is very similar to above one. When you use template as a content, you can pass additional data to it.

    this.overlay = this._toppy
      .position(position)
      .content(template, { name: 'Johny' })
      .create();

    Then in your template you can refer the data like this,

    <ng-template #tpl let-toppy>
      <div>Hello <span [innerText]="toppy.name"></span> !</div>
      <button (click)="toppy.close()">Close</button>
    </ng-template>

    Method close is automatically binded.

    Plain text

    When you use Plain text as a content, optionally you can able to set a class name to that div block.

    this.overlay = this._toppy
      .position(position)
      .content('some content', { class: 'tooltip' })
      .create();

    API

     
    /* Toppy */
     
    Toppy.position(positionToppyPosition):Toppy
     
    Toppy.config(configToppyConfig):Toppy
     
    Toppy.content(dataContentData, propsContentProps = {}):Toppy
     
    Toppy.create(keystring = ''):ToppyControl
     
    Toppy.getCtrl(idstring):ToppyControl
     
    Toppy.destroy():void
     
    /* ToppyControl */
     
    ToppyControl.open():void
     
    ToppyControl.close():void
     
    ToppyControl.toggle():void
     
    ToppyControl.onDocumentClick():Observable<any>
     
    ToppyControl.onWindowResize():Observable<any>
     
    ToppyControl.changePosition(newPositionToppyPosition)void
     
    ToppyControl.updateContent(contentContentData, propsContentProps = {}):void
     
    ToppyControl.updatePosition(config:object):ToppyControl
     
    ToppyControl.listen(eventName:string):Observable<any>
    /* events */
     
    `t_open`, `t_close`, `t_dynpos`, `t_detach`, `t_posupdate`, `t_compins`;

    Contribution

    Any kind of contributions ( Typo fix, documentation, code quality, performance, refactor, pipeline, etc., ) are welcome. :)

    Credits

    ▶ Icons ━ icons8

    ▶ Illustrations ━ undraw

    ▶ Font icons ━ feathers

    Issues

    Found a bug? Have some idea? Or do you have questions? File it here

    Licence

    MIT

    Install

    npm i toppy

    DownloadsWeekly Downloads

    78

    Version

    2.3.4

    License

    MIT

    Unpacked Size

    900 kB

    Total Files

    57

    Last publish

    Collaborators

    • lokesh-coder