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

Demo and documentation
https://lokesh-coder.github.io/toppy/

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.overlayIns = this._toppy
      .overlay(position)
      .host('hello') // content
      .create();
  }

  open() {
    this.overlayIns.open();
  }

  close() {
    this.overlayIns.close();
  }
}

Content

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

Plain text

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

HTML content

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

Using TemplateRef

<ng-template #tpl>Hello world!</ng-template>

@ViewChild('tpl') tpl:TemplateRef<any>;

this.overlayIns = this._toppy
  .overlay(position)
  .host(this.tpl) // template ref
  .create();

Component

// host component
@Component({
  template: '<div>Hello</div>'
})
export class HelloComponent {}

this.overlayIns = this._toppy
  .overlay(position)
  .host(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
  hostWidth: string | number, // content width eg, `auto`, 150, `30%`
  hostHeight: string | number, // content height eg, `auto`, 150, `30%`
  autoUpdate: boolean // update position when window scoll/resize
});

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.
  hostWidth: string | number, // content width eg, `auto`, `150`, `30%`
  hostHeight: 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
  .overlay(position, configuration)
  .host('hello')
  .create();

property	default	supported values
backdrop	false	boolean
containerClass	'toppy-container'	string
wrapperClass	'toppy-wrapper'	string
backdropClass	'toppy-backdrop'	string
bodyClassNameOnOpen	''	string
dismissOnDocumentClick	true	boolean
closeOnEsc	false	boolean
parentElement	null	HTMLElement
watchDocClick	true	boolean
watchWindowResize	true	boolean
windowResizeCallback	null	function
docClickCallback	null	function

Component communication

When you host a component, you can control the overlay through CurrentOverlay service. As of now, this service has only one method called close to close the overlay from the host component. But, soon more API will be added to this service.

// host component
@Component({
  template: '<div>Some text</div>'
})
export class HostComponent {
  constructor(private _overlay: CurrentOverlay) {}

  close() {
    this._overlay.close();
  }
}

You can also set properties to component when creating the overlay.

this.overlayIns = this._toppy
  .overlay(position)
  .host(HelloComponent, { propName: 'toppy-test-prop' })
  .create();

Now automatically all props are attached to host component and you can access it like,

// host component
@Component({
  template: '<div>Some text</div>'
})
export class HostComponent {
  propName; // else tslint will throw error
  constructor() {
    console.log(this.propName); // will return 'toppy-test-prop'
  }
}

API

Toppy.overlay(position:Position, config:ToppyConfig):Toppy

Toppy.host(
  content: string | TemplateRef<any> | ComponentType<any>,
  props: { [x: string]: any } = {}
):Toppy

Toppy.create(position:Position, config:ToppyConfig):ToppyRef

---

ToppyRef.open():void

ToppyRef.close():void

ToppyRef.toggle():void

ToppyRef.onDocumentClick():Observable

ToppyRef.onWindowResize():Observable

ToppyRef.getConfig():ToppyConfig

ToppyRef.updateHost(
  content: string | TemplateRef<any> | ComponentType<any>,
  props: { [x: string]: any } = {}
):ToppyRef

ToppyRef.updatePosition(config:object):ToppyRef

Contribution

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

Issues

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

Licence

MIT