Skip to content
Overlay library for Angular 7+
TypeScript JavaScript Other
Branch: master
Clone or download
semantic-release-bot 🔥 chore(release): 2.3.4 [skip ci]
## [2.3.4](v2.3.3...v2.3.4) (2019-07-31)

### Bug Fixes

* backdrop custom class not added ([#35](#35)) ([23752b9](23752b9))
Latest commit 3129723 Jul 31, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs
e2e feat: initial commit Oct 30, 2018
projects/toppy fix: backdrop custom class not added (#35) Jul 31, 2019
scripts build: add remark plugin to convert heading to link Dec 19, 2018
.editorconfig
.gitignore
.prettierrc feat: initial commit Oct 30, 2018
.releaserc build: add emoji in release commit message Jan 5, 2019
.stylelintrc feat: initial commit Oct 30, 2018
.travis.yml fix: replace codeclimate with codecov config in travis Nov 28, 2018
CHANGELOG.md 🔥 chore(release): 2.3.4 [skip ci] Jul 31, 2019
LICENSE chore: added licence file Nov 22, 2018
README.md docs: update api for newly added `t-compins` event and credits section Jan 5, 2019
angular.json fix: multiple toppy config override (#8) Nov 22, 2018
commitlint.config.js feat: initial commit Oct 30, 2018
package-lock.json
package.json
tsconfig.json feat: initial commit Oct 30, 2018
tslint.json

README.md


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(position: ToppyPosition)
  .config(configuration: ToppyConfig = {})
  .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(position: ToppyPosition):Toppy

Toppy.config(config: ToppyConfig):Toppy

Toppy.content(data: ContentData, props: ContentProps = {}):Toppy

Toppy.create(key: string = ''):ToppyControl

Toppy.getCtrl(id: string):ToppyControl

Toppy.destroy():void
/* ToppyControl */

ToppyControl.open():void

ToppyControl.close():void

ToppyControl.toggle():void

ToppyControl.onDocumentClick():Observable<any>

ToppyControl.onWindowResize():Observable<any>

ToppyControl.changePosition(newPosition: ToppyPosition): void

ToppyControl.updateContent(content: ContentData, props: ContentProps = {}):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

You can’t perform that action at this time.