Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ncstate-sat/popover

Popover component for Angular
https://github.com/ncstate-sat/popover

angular angular-component overlay popover popup

Last synced: 23 days ago
JSON representation

Popover component for Angular

Awesome Lists containing this project

README 

        
# Popover Component for Angular



[![npm version](https://badge.fury.io/js/%40ncstate%2Fsat-popover.svg)](https://badge.fury.io/js/%40ncstate%2Fsat-popover)

[![Build Status](https://travis-ci.org/ncstate-sat/popover.svg?branch=master)](https://travis-ci.org/ncstate-sat/popover)



[Demo](https://stackblitz.com/edit/ncstate-sat-popover-examples) |

[StackBlitz Template](https://stackblitz.com/edit/ncstate-sat-popover-issues) |

[Development App](https://ncstate-sat.github.io/popover/)



## Installation



`sat-popover` has a peer dependency on the Angular CDK to leverage its overlay API.



```bash

npm install --save @ncstate/sat-popover @angular/cdk

```



If you want the popover animations to work, you must include `BrowserAnimationsModule` in your app.



```ts

import { BrowserAnimationsModule } from '@angular/platform-browser/animations';



@NgModule({

  ...

  imports: [ BrowserAnimationsModule ],

  ...

})

export class AppModule { }

```



If you prefer to not have animations, you can include `NoopAnimationsModule`.



```ts

import { NoopAnimationsModule } from '@angular/platform-browser/animations';



@NgModule({

  ...

  imports: [ NoopAnimationsModule ],

  ...

})

export class AppModule { }

```



Finally, import the `SatPopoverModule` to provide the necessary components and directives.



```ts

import { SatPopoverModule } from '@ncstate/sat-popover';



@NgModule({

  ...

  imports: [ SatPopoverModule ],

  ...

})

export class AppModule { }

```



## Usage



### Getting started



Wrap any component you want to display in a popover with an `` component.



```html



  



```



Next, apply the `satPopoverAnchor` directive to the element you wish to be the popover anchor and pass the `` component as an argument to the `satPopoverAnchor` directive.



```html

 See Contact Details 



  



```



> Note: `hasBackdrop` is explained below



Alternatively, supply an anchor element to the popover.



```html

 See Contact Details 



  



```



### Alignment



By default, the popover will appear centered over the anchor. If you instead want the popover

to appear below the anchor:



```html



  



```



You can use the following to align the popover around the anchor:



| Input             | Type                                                | Default  |

| ----------------- | --------------------------------------------------- | -------- |

| `horizontalAlign` | 'before' \| 'start' \| 'center' \| 'end' \| 'after' | 'center' |

| `verticalAlign`   | 'above' \| 'start' \| 'center' \| 'end' \| 'below'  | 'center' |



For convenience, you can also use `xAlign` and `yAlign` as shorthand for `horizontalAlign`

and `verticalAlign`, respectively.



By default, if the popover cannot fully fit within the viewport, it will use a fallback

alignment. You can use `forceAlignment` to ensure that the popover always displays

with the alignment you've specified.



```html



  



```



Also by default, as the user scrolls or changes the viewport size, the popover will attempt

to stay within the viewport by using a fallback position (provided `forceAlignment` is not

set). You can use `lockAlignment` to ensure the popover does not change its alignment once

opened.



```html



  



```



### Opening and closing



You are in full control of when the popover opens and closes. You can hook into any event or

trigger that fits your application's needs.



#### `SatPopover` has the following methods and outputs



| Method  | Description                                  |

| ------- | -------------------------------------------- |

| open    | Open the popover.                            |

| close   | Close the popover. Optionally takes a value. |

| toggle  | Toggle the popover open or closed.           |

| isOpen  | Get whether the popover is presently open.   |

| realign | Realign the popover to the anchor.           |



| Output          | Description                                                       |

| --------------- | ----------------------------------------------------------------- |

| opened          | Emits when the popover is opened.                                 |

| closed          | Emits when the popover is closed.                                 |

| afterOpen       | Emits when the popover has finished opening.                      |

| afterClose      | Emits when the popover has finished closing.                      |

| backdropClicked | Emits when the popover's backdrop (if enabled) is clicked.        |

| overlayKeydown  | Emits when a keydown event is targeted to this popover's overlay. |



#### `SatPopoverAnchor` has the following properties



| Property                  | Description                                       |

| ------------------------- | ------------------------------------------------- |

| popover                   | A handle to the associated popover.               |

| satPopoverAnchor (setter) | An `@Input()` for setting the associated popover. |

| elementRef                | The ElementRef for with the anchor.               |

| viewContainerRef          | The ViewContainerRef for the anchor.              |



### Focus behavior



By default, the popover will apply focus to the first tabbable element when opened and trap focus

within the popover until closed. If the popover does not contain any focusable elements, focus

will remain on the most recently focused element.



You can target a different element for initial focus using the `cdkFocusInitial` attribute.



To prevent focus from automatically moving into the popover, you can set the `autoFocus` property

to `false`.



```html



  



```



Once the popover is closed, focus will return to the most recently focused element prior to

opening the popover. To disable this, you can set the `restoreFocus` property to `false`.



```html



  



```



Alternatively the `open` method supports an optional `SatPopoverOpenOptions`

object where `autoFocus` and `restoreFocus` options can be set while opening the popover. Note

that these options do no take precendence over the component inputs. For example, if `restoreFocus`

is set to `false` either in the open options or via the component input, focus will not be

restored.



```html

 Open 

```



### Backdrop



You can add a fullscreen backdrop that appears behind the popover when it is open. It prevents

interaction with the rest of the application and will automatically close the popover when

clicked. To add it to your popover, use `hasBackdrop`.



```html



  



```



If used, the default backdrop will be transparent. You can add any custom backdrop class with

`backdropClass`.



```html



  



```



> Note: if you plan on using `mouseenter` and `mouseleave` events to open and close your popover,

> keep in mind that a backdrop will block pointer events once it is open, immediately triggering

> a `mouseleave` event.



### Overlay panel



You can add custom css classes to the overlay panel that wraps the popover.



```html



  



```



### Interactive closing



If your popover has a backdrop, it will automatically close when clicked. The popover will also

automatically close when esc is pressed. These two behaviors are wrapped in the

`interactiveClose` property, which defaults to `true`. Set `interactiveClose` to `false` to prevent

the popover from automatically closing on these user interactions.



```html



  



```



If you wish to only disable the automatic esc behavior, you must disable all

interactive close options and then manually react to `backdropClicked` events.



```html



  



```



### Scrolling



By default, when a popover is open and the user scrolls the container, the popover will reposition

itself to stay attached to its anchor. You can adjust this behavior with `scrollStrategy`.



```html



  



```



| Strategy       | Description                                 |

| -------------- | ------------------------------------------- |

| `'noop'`       | Don't update position.                      |

| `'block'`      | Block page scrolling while open.            |

| `'reposition'` | Reposition the popover on scroll (default). |

| `'close'`      | Close the popover on scroll.                |



> Note: if your popover fails to stay anchored with the `reposition` strategy, you may need to add

> the [`cdkScrollable`](https://material.angular.io/cdk/scrolling/overview) directive to your

> scrolling container. This will ensure scroll events are dispatched to the popover's positioning

> service.



### Animations



By default, the opening and closing animations of a popover are quick with a simple easing curve.

You can modify these animation curves using `openTransition` and `closeTransition`.



```html



  



```



You can also modify the default transition globally by adding a custom value to the

`DEFAULT_TRANSITION` provider.



```ts

import { SatPopoverModule, DEFAULT_TRANSITION } from '@ncstate/sat-popover';



@NgModule({

  ...

  imports: [ SatPopoverModule ],

  providers: [

    { provide: DEFAULT_TRANSITION, useValue: '300ms ease' }

  ]

  ...

})

export class AppModule { }

```



Additionally you can modify the scale values for the opening (`startAtScale`) and closing (`endAtScale`) animations.



```html



  



```



## Styles



The `` component only provides styles to affect its own transform origin. It is

the responsibility of the elements you project inside the popover to style themselves. This

includes background color, box shadows, margin offsets, etc.



## Add-on behaviors



### Hover



The `SatPopoverHoverDirective` is available as a way to automatically add hover logic to your

anchor with an optional delay. The `SatPopoverHoverDirective` must be used in conjunction

with `SatPopoverAnchor`.



```html

 Hover to show tooltip after 1 second 


```



```html

 Hover this text to show tooltip immediately 


```