@ncstate/sat-popover

Popover Component for Angular

Demo | StackBlitz Template | Development App

Installation

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

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

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

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

@NgModule({
  ...
  imports: [ BrowserAnimationsModule ],
  ...
})
export class AppModule { }

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

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

@NgModule({
  ...
  imports: [ NoopAnimationsModule ],
  ...
})
export class AppModule { }

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

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 <sat-popover> component.

<sat-popover>
  <app-contact-overview [contact]="myContact"></app-contact-overview>
</sat-popover>

Next, hook the popover to an anchor element.

<button [satPopoverAnchorFor]="contactPopover" (click)="contactPopover.toggle()">
  See Contact Details
</button>

<sat-popover #contactPopover hasBackdrop>
  <app-contact-overview [contact]="myContact"></app-contact-overview>
</sat-popover>

Note: hasBackdrop is explained below

Alignment

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

<sat-popover #contactPopover verticalAlign="below">
  <!-- ... -->
</sat-popover>

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.

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.

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.

SatPopoverAnchor has the following methods and outputs

Method	Description
openPopover	Open the popover.
closePopover	Close the popover. Optionally takes a value.
togglePopover	Toggle the popover open or closed.
isPopoverOpen	Get whether the popover is presently open.

Output	Description
popoverOpened	Emits when the popover is opened.
popoverClosed	Emits when the popover is closed.

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.

<sat-popover #myBlockingPopover hasBackdrop>
  <!-- ... -->
</sat-popover>

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

<sat-popover #myBlockingPopover hasBackdrop backdropClass="app-fancy-backdrop">
  <!-- ... -->
</sat-popover>

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.

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.

<sat-popover #importantPopover scrollStrategy="block">
  <!-- so important that the user must interact with it -->
</sat-popover>

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 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.

<!-- open slowly but close quickly -->
<sat-popover #mySlowPopover
    openTransition="1000ms ease-out"
    closeTransition="100ms ease-in">
  <!-- ... -->
</sat-popover>

Styles

The <sat-popover> 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.

Changelog

1.0.0-beta.2 deserting-descartes

Breaking Changes

The biggest change this release is how positioning the popover works. You can now align popovers at the start or end of the anchor, on either or both axes. This removes the need to have an overlapAnchor option. Further, to better describe the intention of the positioning parameters, xPosition has been renamed to horizontalAlign and yPosition has been renamed to verticalAlign.

We hope these two changes will make it easier to depict a mental model of the expected behavior. It also gives you 8 more possible positions!

This table should give you an idea of how to migrate:

| Previously | Currently | | ----------------------------------------- | ------------------------- | | xPosition="before" overlapAnchor="true" | horizontalAlign="end" | | xPosition="after" overlapAnchor="false" | horizontalAlign="after" | | yPosition="below" overlapAnchor="true" | verticalAlign="start" | | yPosition="above" overlapAnchor="false" | verticalAlign="above" |

For convenience, aliases have also been provided

| Input | Alias | | ----------------- | -------- | | horizontalAlign | xAlign | | verticalAlign | yAlign |

The following have also been renamed:

• SatPopoverPositionX -> SatPopoverHorizontalAlign
• SatPopoverPositionY -> SatPopoverVerticalAlign

Features

• Add start and end options to horizontalAlign and verticalAlign.
• Use better fallback strategy that originates from target alignment
• The popover now has afterOpen and afterClose outputs that emit when the animation is complete
• The popover now has a 'close' scroll strategy. It will close itself whenever the parent container is scrolled.

Fixes

• Switch to rxjs lettable operators to avoid polluting user's global Rx prototype
• Allow user to declare popover eariler in a template than the anchor

Other

• Fix typo in readme
• Publish demo app at https://ncstate-sat.github.io/popover/
• Add stacblitz starter to readme and issue template
• Rename 'position' to 'align' and 'x/y' to 'horizontal/vertical'
• Support cdk @ 5.0.0-rc0 and Angular 5