ngx-popper is an Angular wrapper for @popperjs
npm install ng-popperjs[![npm][badge-npm-version]][url-npm] [![npm][badge-npm-downloads]][url-npm] [![MIT licensed][badge-licence]][url-licence] [![Build state][badge-ci-state]][url-ci-state] [![Size][badge-bundle]][url-bundle] [![Rate this package][badge-openbase]][url-openbase]
ngx-popperjs is an angular wrapper for the Popper.js library.
Note that I also updated everything to use Popper 2 (v 2.4.4 in v 9.0.0)
The goal of this library is to take Mr Frankel's ngx-popper and update the compatibility for more recent versions of Angular.
Since the old library is compatible with Angular 7 and earlier, I started with Angular 8.
If you need to work with an older version of Angular (5 to 7), please refer to Mr Frankel's ngx-popper.
Since many complained about using the NgxPopperjsPlacements enum, I added a version of the popper directive which accepts a plain string as placement!
Now you can use it with all the options of the classic popper, but you'll have to use:
popperLoose instead of popper
and
popperLoosePlacement instead of popperPlacement
node and npm are required to run this package.
1. Use npm/yarn to install the package:
``terminal`
$ npm install @popperjs/core ngx-popperjs --save
Or
terminal`
$ yarn add @popperjs/core --save
$ yarn add ngx-popperjs --save
2. You simply add into your module NgxPopperjsModule:
`typescript`
import {NgxPopperjsModule} from 'ngx-popperjs';
@NgModule({
// ...
imports: [
// ...
NgxPopperjsModule
]
})
Optionally you can include in your styles.css / styles.css one of the prebuilt themes:@import node_modules/ngx-popperjs/css/theme-dark.css
*
*
* @use ngx-popperjs/scss/theme as popperBaseTheme
*
*
or easily create your own theme using the @mixin:
`
@use "ngx-popperjs/scss/theme" as popperBaseTheme;
body {
@include popperjs.ngx-popperjs-theme($background-color, $text-color, $max-width, $z-index);
}
`
3. Add to view:
` Popper on bottom Hey! Choose where to put your popper!HTML
[popperShowOnStart]="true"
[popperTrigger]="'click'"
[popperHideOnClickOutside]="true"
[popperHideOnScroll]="true"
[popperPlacement]="'bottom'">
4. As text:
HTML
[popperTrigger]="'hover'"
[popperPlacement]="'bottom'"
(popperOnShown)="onShown($event)">
Pop
on the bottom
HTML
[popperTrigger]="'hover'"
[popperPlacement]="'bottom'"
[popperStyles]="{'background-color: 'blue''}",
(popperOnShown)="onShown($event)">
Pop
on the bottom
5. Position fixed, breaking overflow:
HTML
[popperTrigger]="'hover'"
[popperPlacement]="'bottom'"
[popperPositionFixed]="true"
(popperOnShown)="onShown($event)">
6. Specific target:
HTML
popperTrigger="hover"
popperPlacement="bottom"
[popperTarget]="popperTargetElement.nativeElement"
(popperOnShown)="onShown($event)">
`
7. hide/show programmatically:
HTML
popperTrigger="hover"
popperPlacement="bottom"
[popperApplyClass]="'popperSpecialStyle'">
Pop
on the bottom
This is a tooltip with text
8. Attributes map:
| Option | Type | Default | Description |
|:----------------------- |:---------------- |:--------- | :------------------------------------------------------------------------------------------------------ |
| popperDisableAnimation | boolean | false | Disable the default animation on show/hide |
| popperDisableStyle | boolean | false | Disable the default styling |
| popperDisabled | boolean | false | Disable the popper, ignore all events |
| popperDelay | number | 0 | Delay time until popper it shown |
| popperTimeout | number | 0 | Set delay before the popper is hidden |
| popperTimeoutAfterShow | number | 0 | Set a time on which the popper will be hidden after it is shown |
| popperPlacement | Placement(string) | auto | The placement to show the popper relative to the reference element |
| popperTarget | HtmlElement | auto | Specify a different reference element other the the one hosting the directive |
| popperBoundaries | string(selector) | undefined | Specify a selector to serve as the boundaries of the element |
| popperShowOnStart | boolean | false | Popper default to show |
| popperTrigger | Trigger(string) | click | Trigger/Event on which to show/hide the popper |
| popperPositionFixed | boolean | false | Set the popper element to use position: fixed |
| popperAppendTo | string | undefined | append The popper-content element to a given selector, if multiple will apply to first |
| popperPreventOverflow | boolean | undefined | Prevent the popper from being positioned outside the boundary |
| popperHideOnClickOutside | boolean | true | Popper will hide on a click outside |
| popperHideOnScroll | boolean | false | Popper will hide on scroll |
| popperHideOnMouseLeave | boolean | false | Popper will hide on mouse leave |
| popperModifiers | popperModifier | undefined | popper.js custom modifiers hock |
| popperApplyClass | string | undefined | list of comma separated class to apply on ngpx__container |
| popperStyles | Object | undefined | Apply the styles object, aligned with ngStyles |
| popperApplyArrowClass | string | undefined | list of comma separated class to apply on ngpx__arrow |
| popperOnShown | EventEmitter<> | $event | Event handler when popper is shown |
| popperOnHidden | EventEmitter<> | $event | Event handler when popper is hidden |
| popperOnUpdate | EventEmitter<> | $event | Event handler when popper is updated |
| popperAriaDescribeBy | string | undefined | Define value for aria-describeby attribute |
| popperAriaRole | string | popper | Define value for aria-role attribute |
9. Override defaults:
ngx-popperjs comes with a few default properties you can override in default to effect all instances
These are overridden by any child attributes.
JavaScript
NgModule({
imports: [
BrowserModule,
FormsModule,
NgxPopperjsModule.forRoot({placement: NgxPopperjsPlacements.TOP})],
declarations: [AppComponent],
providers: [],
bootstrap: [AppComponent]});
`
| Options | Type | Default |
|:------------------- |:---------------- |:--------- |
| showDelay | number | 0 |
| disableAnimation | boolean | false |
| disableDefaultStyling | boolean | false |
| placement | Placement(string) | auto |
| boundariesElement | string(selector) | undefined |
| trigger | Trigger(string) | hover |
| popperModifiers | popperModifier | undefined |
| positionFixed | boolean | false |
| hideOnClickOutside | boolean | true |
| hideOnMouseLeave | boolean | false |
| hideOnScroll | boolean | false |
| applyClass | string | undefined |
| styles | Object | undefined |
| applyArrowClass | string | undefined |
| ariaDescribeBy | string | undefined |
| ariaRole | string | undefined |
| appendTo | string | undefined |
| preventOverflow | boolean | undefined |10. popperPlacement:
| 'top'
| 'bottom'
| 'left'
| 'right'
| 'top-start'
| 'bottom-start'
| 'left-start'
| 'right-start'
| 'top-end'
| 'bottom-end'
| 'left-end'
| 'right-end'
| 'auto'
| 'auto-start'
| 'auto-end'
| Function
11. popperTrigger:
| 'click'
| 'mousedown'
| 'hover'
| 'none'
$3
Demo of ngx-popperjs$3
You can only report bugs. Every other issue will be deleted right away.
terminal
$ npm install
$ npm run start //run example
``Jetbrains is now supporting this library with an open-source license, which will allow a better code! 🎉
This project is licensed under the MIT License - see the LICENSE file for details
MrFrankel for setting up ngx-popper and maintaining till v 7.0.0.
[badge-bundle]: https://img.shields.io/bundlephobia/minzip/ngx-popperjs
[badge-ci-state]: https://github.com/tonysamperi/ngx-popperjs/actions/workflows/main.yml/badge.svg
[badge-licence]: https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square
[badge-npm-downloads]: https://img.shields.io/npm/dm/ngx-popperjs.svg?style=flat-square
[badge-npm-version]: https://img.shields.io/npm/v/ngx-popperjs.svg?style=flat-square
[badge-openbase]: https://badges.openbase.com/js/rating/ngx-popperjs.svg
[url-bundle]: https://img.shields.io/bundlephobia/minzip/ngx-popperjs
[url-ci-state]: https://github.com/tonysamperi/ngx-popperjs/actions
[url-licence]: https://github.com/tonysamperi/ngx-popperjs/blob/master/LICENSE
[url-npm]: https://www.npmjs.com/package/ngx-popperjs
[url-openbase]: https://openbase.com/js/ngx-popperjs