{"id":13495311,"url":"https://github.com/lokesh-coder/toppy","last_synced_at":"2025-03-16T16:31:52.640Z","repository":{"id":33360875,"uuid":"151297892","full_name":"lokesh-coder/toppy","owner":"lokesh-coder","description":"Overlay library for Angular 7+","archived":false,"fork":false,"pushed_at":"2022-06-02T20:47:24.000Z","size":1579,"stargazers_count":83,"open_issues_count":15,"forks_count":8,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-03-14T20:38:45.253Z","etag":null,"topics":["angular","dropdown","modal","overlay","popover","sidebar","toast","tooltip"],"latest_commit_sha":null,"homepage":"https://lokesh-coder.github.io/toppy/","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/lokesh-coder.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-10-02T17:49:12.000Z","updated_at":"2023-06-29T02:33:26.000Z","dependencies_parsed_at":"2022-09-26T16:22:02.371Z","dependency_job_id":null,"html_url":"https://github.com/lokesh-coder/toppy","commit_stats":null,"previous_names":[],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lokesh-coder%2Ftoppy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lokesh-coder%2Ftoppy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lokesh-coder%2Ftoppy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lokesh-coder%2Ftoppy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lokesh-coder","download_url":"https://codeload.github.com/lokesh-coder/toppy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243822295,"owners_count":20353500,"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","dropdown","modal","overlay","popover","sidebar","toast","tooltip"],"created_at":"2024-07-31T19:01:33.406Z","updated_at":"2025-03-16T16:31:52.216Z","avatar_url":"https://github.com/lokesh-coder.png","language":"TypeScript","readme":"\u003ch1 align=\"center\"\u003e\n  \u003cbr\u003e\n  \u003ca href=\"https://lokesh-coder.github.io/toppy/\"\u003e\u003cimg src=\"./docs/assets/toppy-logo.png\" alt=\"Toppy\" width=\"100\"\u003e\u003c/a\u003e\u003cbr\u003e\n\u003c/h1\u003e\n\n\u003ch4 align=\"center\"\u003eTiny Angular library to create overlays for tooltips, modals, dropdowns, alerts, toastr, popovers, menus, and more\u003c/h4\u003e\n\n\u003cp align=\"center\"\u003e\n \u003ca href=\"https://github.com/lokesh-coder/toppy/releases\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/release/lokesh-coder/toppy.svg?style=flat-square\u0026colorA=0C0B0C\u0026colorB=2C282C\" alt=\"Github Release\"\u003e\n  \u003c/a\u003e\n   \u003ca href=\"LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/l/toppy.svg?style=flat-square\u0026colorA=0C0B0C\u0026colorB=2C282C\" alt=\"Licence\"\u003e\n  \u003c/a\u003e\n   \u003ca href=\"#\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/dm/toppy.svg?style=flat-square\u0026colorA=0C0B0C\u0026colorB=2C282C\" alt=\"Downloads\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\u003cbr\u003e\n\n\u003cdiv class=\"highlight highlight-source-shell\"\u003e\n\u003cpre\u003e\n\u003cdiv align=\"center\"\u003e\u003cstrong \u003eDemo and documentation\u003c/strong\u003e\u003c/div\u003e\n\u003cdiv align=\"center\"\u003e\u003ca align=\"center\" href=\"https://lokesh-coder.github.io/toppy/\"\u003ehttps://lokesh-coder.github.io/toppy/\u003c/a\u003e\u003c/div\u003e\n\u003c/pre\u003e\n\u003c/div\u003e\n\n### Installation\n\n**step 1:** Install from [npm](https://www.npmjs.com/package/toppy) or [yarn](https://yarnpkg.com/en/package/toppy)\n\n```sh\nnpm install toppy // or\nyarn add toppy\n```\n\n**step 2:** Import `ToppyModule` in your main module\n\n```typescript\nimport { ToppyModule } from 'toppy';\n\n@NgModule({\n  declarations: [AppComponent],\n  imports: [BrowserModule, ToppyModule], // \u003c==\n  bootstrap: [AppComponent]\n})\nexport class AppModule {}\n```\n\n**step 3:** Import `Toppy` service in your component\n\n```typescript\nimport { Toppy } from 'toppy'; // \u003c==\n\n@Component({\n  selector: 'app-root',\n  template: '\u003cdiv #el\u003eClick me\u003c/div\u003e'\n})\nexport class AppComponent {\n  @ViewChild('el', { read: ElementRef })\n  el: ElementRef;\n\n  constructor(private _toppy: Toppy) {}\n\n  ngOnInit() {\n    const position = new RelativePosition({\n      placement: OutsidePlacement.BOTTOM_LEFT,\n      src: this.el.nativeElement\n    });\n\n    this.overlay = this._toppy\n      .position(position)\n      .content('hello') // content\n      .create();\n  }\n\n  open() {\n    this.overlay.open();\n  }\n\n  close() {\n    this.overlay.close();\n  }\n}\n```\n\n### Content\n\nToppy allows to use `string`, `html`, `TemplateRef`, `Component` as overlay content.\n\n**Plain text**\n\n```typescript\nthis.overlay = this._toppy\n  .position(position)\n  .content(`some plain text content`) // simple text\n  .create();\n```\n\n**HTML content**\n\n```typescript\nthis.overlay = this._toppy\n  .position(position)\n  .content(`\u003cdiv\u003eany HTML content\u003c/div\u003e`, { hasHTML: true }) // html\n  .create();\n```\n\n**Using TemplateRef**\n\n```html\n\u003cng-template #tpl\u003eHello world!\u003c/ng-template\u003e\n```\n\n```typescript\n@ViewChild('tpl') tpl:TemplateRef\u003cany\u003e;\n\nthis.overlay = this._toppy\n  .position(position)\n  .content(this.tpl) // template ref\n  .create();\n```\n\n**Component**\n\n```typescript\n// host component\n@Component({\n  template: '\u003cdiv\u003eHello\u003c/div\u003e'\n})\nexport class HelloComponent {}\n```\n\n```typescript\nthis.overlay = this._toppy\n  .position(position)\n  .content(HelloComponent) // \u003c==\n  .create();\n```\n\n\u003e Dont forget to add host component in `entryComponents` in module\n\n### Positions\n\nPosition determines the location and size of the overlay. There are four positions:\n\n**Relative position**\n\nOverlay position that is relative to specific element. These are used in `tooltips`, `popovers`, `dropdowns`, `menus`\n\n```typescript\nnew RelativePosition({\n  src: HTMLElement, // target element\n  placement: OutsidePlacement, // location of the content\n  width: string | number, // content width eg, `auto`, 150, `30%`\n  height: string | number, // content height eg, `auto`, 150, `30%`\n  autoUpdate: boolean // update position when window scroll/resize/drag\n});\n```\n\nRelative position supports 12 placements:\n\n```typescript\nOutsidePlacement.BOTTOM;\nOutsidePlacement.BOTTOM_LEFT;\nOutsidePlacement.BOTTOM_RIGHT;\nOutsidePlacement.LEFT;\nOutsidePlacement.LEFT_BOTTOM;\nOutsidePlacement.LEFT_TOP;\nOutsidePlacement.RIGHT;\nOutsidePlacement.RIGHT_BOTTOM;\nOutsidePlacement.RIGHT_TOP;\nOutsidePlacement.TOP;\nOutsidePlacement.TOP_LEFT;\nOutsidePlacement.TOP_RIGHT;\n```\n\n**Global position**\n\nOverlay position that is relative to window viewport. These are used in `modals`, `alerts`, `toastr`\n\n```typescript\nnew GlobalPosition({\n  placement: InsidePlacement, // location of the content.\n  width: string | number, // content width eg, `auto`, `150`, `30%`\n  height: string | number, //content height eg, `auto`, 150, `30%`\n  offset: number // oustide space of the content, in px\n});\n```\n\nGlobal position supports 9 placements:\n\n```typescript\nInsidePlacement.BOTTOM;\nInsidePlacement.BOTTOM_LEFT;\nInsidePlacement.BOTTOM_RIGHT;\nInsidePlacement.LEFT;\nInsidePlacement.RIGHT;\nInsidePlacement.TOP;\nInsidePlacement.TOP_LEFT;\nInsidePlacement.TOP_RIGHT;\nInsidePlacement.CENTER;\n```\n\n**Slide position**\n\nOverlay position that is relative to window viewport. These are used in `side panels`, `sidebars`, `blade`\n\n```typescript\nnew SlidePosition({\n  placement: SlidePlacement, // rigth or left\n  width: string // width eg, '300px' or '30%'\n});\n```\n\nSlide position supports 2 placements:\n\n```typescript\nSlidePlacement.LEFT;\nSlidePlacement.RIGHT;\n```\n\n**Fullscreen position**\n\nOverlay that occupies complete size of the viewport.\n\n```typescript\nnew FullScreenPosition();\n```\n\n### Configuration\n\n```typescript\nthis.toppy\n  .position(position: ToppyPosition)\n  .config(configuration: ToppyConfig = {})\n  .content('hello')\n  .create();\n```\n\n| `property`               | `for`                                                                                  |\n| ------------------------ | -------------------------------------------------------------------------------------- |\n| **backdrop**             | `boolean` \u0026middot; whether to show backdrop layer \u0026middot; default: `false`            |\n| **closeOnEsc**           | `boolean` \u0026middot; clicking Escape button will close overlay \u0026middot; default: `false` |\n| **closeOnDocClick**      | `boolean` \u0026middot; dismiss on clicking outside of content \u0026middot; default: `false`    |\n| **listenWindowEvents**   | `boolean` \u0026middot; auto adjust the position on scroll/resize \u0026middot; default: `true`  |\n| **containerClass**       | `string` \u0026middot; overlay container class name \u0026middot; default: `t-overlay`           |\n| **wrapperClass**         | `string` \u0026middot; overlay wrapper class name \u0026middot; default: `''`                    |\n| **backdropClass**        | `string` \u0026middot; overlay backdrop class name \u0026middot; default: `''`                   |\n| **bodyClass**            | `string` \u0026middot; body class when overlay is open \u0026middot; default: `t-open`           |\n| **windowResizeCallback** | `function` \u0026middot; triggered on window scroll                                         |\n| **docClickCallback**     | `function` \u0026middot; triggered on document click                                        |\n\n### Component communication\n\n#### Component Data\n\nWhen 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`.\n\n```typescript\nthis.overlay = this._toppy\n  .position(position)\n  .content(HelloComponent, { propName: 'toppy-test-prop' })\n  .create();\n\nthis.overlay.listen('t_compins').subscribe(comp =\u003e {\n  console.log('component is ready!', comp); // returns HelloComponent\n});\n```\n\n```typescript\n// host component\n@Component({\n  template: '\u003cdiv\u003eSome text\u003c/div\u003e'\n})\nexport class HelloComponent {\n  constructor(public overlay: ToppyOverlay) {\n    console.log(this.overlay.props.propName); // will return 'toppy-test-prop'\n  }\n\n  close() {\n    this.overlay.close();\n  }\n}\n```\n\n#### Template Data\n\nThis is very similar to above one. When you use template as a content, you can pass additional data to it.\n\n```typescript\nthis.overlay = this._toppy\n  .position(position)\n  .content(template, { name: 'Johny' })\n  .create();\n```\n\nThen in your template you can refer the data like this,\n\n```html\n\u003cng-template #tpl let-toppy\u003e\n  \u003cdiv\u003eHello \u003cspan [innerText]=\"toppy.name\"\u003e\u003c/span\u003e !\u003c/div\u003e\n  \u003cbutton (click)=\"toppy.close()\"\u003eClose\u003c/button\u003e\n\u003c/ng-template\u003e\n```\n\nMethod `close` is automatically binded.\n\n#### Plain text\n\nWhen you use Plain text as a content, optionally you can able to set a class name to that `div` block.\n\n```typescript\nthis.overlay = this._toppy\n  .position(position)\n  .content('some content', { class: 'tooltip' })\n  .create();\n```\n\n### API\n\n```typescript\n\n/* Toppy */\n\nToppy.position(position: ToppyPosition):Toppy\n\nToppy.config(config: ToppyConfig):Toppy\n\nToppy.content(data: ContentData, props: ContentProps = {}):Toppy\n\nToppy.create(key: string = ''):ToppyControl\n\nToppy.getCtrl(id: string):ToppyControl\n\nToppy.destroy():void\n```\n\n```typescript\n\n/* ToppyControl */\n\nToppyControl.open():void\n\nToppyControl.close():void\n\nToppyControl.toggle():void\n\nToppyControl.onDocumentClick():Observable\u003cany\u003e\n\nToppyControl.onWindowResize():Observable\u003cany\u003e\n\nToppyControl.changePosition(newPosition: ToppyPosition): void\n\nToppyControl.updateContent(content: ContentData, props: ContentProps = {}):void\n\nToppyControl.updatePosition(config:object):ToppyControl\n\nToppyControl.listen(eventName:string):Observable\u003cany\u003e\n```\n\n```typescript\n/* events */\n\n`t_open`, `t_close`, `t_dynpos`, `t_detach`, `t_posupdate`, `t_compins`;\n```\n\n### Contribution\n\nAny kind of contributions ( Typo fix, documentation, code quality, performance, refactor, pipeline, etc., ) are welcome. :)\n\n### Credits\n\n▶ Icons ━ [icons8](https://icons8.com/icons/cotton)\n\n▶ Illustrations ━ [undraw](https://undraw.co/illustrations)\n\n▶ Font icons ━ [feathers](https://feathericons.com)\n\n### Issues\n\nFound a bug? Have some idea? Or do you have questions? File it [here](https://github.com/lokesh-coder/toppy/issues)\n\n### Licence\n\nMIT\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flokesh-coder%2Ftoppy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flokesh-coder%2Ftoppy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flokesh-coder%2Ftoppy/lists"}