Overlay API

This API allows overlay components to be controlled from the PrimeNGConfig. In this way, all overlay components in the application can have the same behavior.

Import #


import { OverlayModule } from 'primeng/overlay';

Basic #

Overlay is a container to display content in an overlay window. All the options mentioned above can be used as props for this component.


<p-button (click)="toggle()" label="Show Overlay"></p-button>
<p-overlay [(visible)]="overlayVisible" [responsive]="{ breakpoint: '640px', direction: 'bottom', contentStyleClass: 'h-20rem' }" contentStyleClass="p-4 surface-overlay shadow-2 border-round">
    Content
</p-overlay>

Template #

Content can be customized with the content template.


<p-button (click)="toggle()" label="Show Overlay"></p-button>
<p-overlay [(visible)]="overlayVisible" [responsive]="{ breakpoint: '640px', direction: 'bottom', contentStyleClass: 'h-20rem' }" contentStyleClass="p-4 surface-overlay shadow-2 border-round">
    <ng-template pTemplate="content" let-option>
        Content - {{option.mode}}
    </ng-template>
</p-overlay>

Options #

Mode #

It has two valid values; overlay and modal. In overlay mode, a container element is opened like overlaypanel or dropdown's panel. In modal mode, the container element behaves like popup. This behaviour is similar to a dialog component. 



import { PrimeNGConfig, OverlayOptions } from 'primeng/api';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html'
})
export class AppComponent implements OnInit {

    constructor(private primengConfig: PrimeNGConfig) {}

    ngOnInit() {
        this.primengConfig.overlayOptions: OverlayOptions = {
            mode: 'modal'
        };
    } 
}

Responsive #

It is the option used to determine in which mode it should appear according to the given media or breakpoint.


import { PrimeNGConfig, OverlayOptions, ResponsiveOverlayDirectionType } from 'primeng/api';

const responsiveOptions: ResponsiveOverlayOptions = {
    // style?: any;                                     // Style of component in given breakpoint or media query
    // styleClass?: string;                             // Style class of component in given breakpoint or media query
    // contentStyle?: any;                              // Style of content in given breakpoint or media query
    // contentStyleClass?: string;                      // Style class of content in given breakpoint or media query
    // breakpoint?: string;                             // Breakpoint required to show component in modal mode. Exp: '640px', '10rem' etc.
    // media?: string;                                  // Media query required to show component in modal mode. Exp: '@media screen and (max-width: 640px)', '@media screen and (min-width: 640px) and (max-width: 900px)' etc.
    // direction?: ResponsiveOverlayDirectionType;      // Direction in which the component will be displayed in modal mode.
    // hideOnEscape?: boolean;                          // Hides overlay when escape key pressed.
}

this.primengConfig.overlayOptions: OverlayOptions = {
    responsive: responsiveOptions
};

Valid values of the direction property would be;

  • center (default)
  • top
  • top-start
  • top-end
  • bottom
  • bottom-start
  • bottom-end
  • left
  • left-start
  • left-end
  • right
  • right-start
  • right-end

AppendTo #

Overlay can be mounted into its location, body or DOM element instance using this option.



import { PrimeNGConfig, OverlayOptions } from 'primeng/api';

this.primengConfig.overlayOptions: OverlayOptions = {
    appendTo: 'body'
};

Target #

The target is used to detect the element that will be used to position the overlay. Valid values would be;

  • @prev (default)
  • @next
  • @parent
  • @grandparent
  • Use CSS selector
  • Use () => HTMLElement

Style #

The style and styleClass are used to define styles that will be added to all overlay components. In addition, it can be used in contentStyle and contentStyleClass classes.

BaseZIndex #

The baseZIndex is base zIndex value to use in layering. Its default value is 0.

AutoZIndex #

The autoZIndex determines whether to automatically manage layering. Its default value is 'false'.

HideOnEscape #

The hideOnEscape determines to hide the overlay when escape key pressed. Accepts boolean, default value is false.

ShowTransitionOptions and HideTransitionOptions #

Transition options of the show or hide animation. The default value of showTransitionOptions is '.12s cubic-bezier(0, 0, 0.2, 1)' and the default value of hideTransitionOptions is '.1s linear'.

Events #



import { PrimeNGConfig, OverlayOptions, OverlayOnBeforeShowEvent, OverlayOnShowEvent, OverlayOnBeforeHideEvent, OverlayOnHideEvent } from 'primeng/api';
import { AnimationEvent } from '@angular/animations';

this.primengConfig.overlayOptions: OverlayOptions = {
    onBeforeShow: (event?: OverlayOnBeforeShowEvent) => {};    // Callback to invoke before the overlay is shown.
    onShow: (event?: OverlayOnShowEvent) => {};                // Callback to invoke when the overlay is shown.
    onBeforeHide: (event?: OverlayOnBeforeHideEvent) => {};    // Callback to invoke before the overlay is hidden.
    onHide: (event?: OverlayOnHideEvent) => {};                // Callback to invoke when the overlay is hidden.
    onAnimationStart: (event?: AnimationEvent) => {};          // Callback to invoke when the animation is started.
    onAnimationDone: (event?: AnimationEvent) => {};           // Callback to invoke when the animation is done.
};

Accessibility #

Screen Reader

Overlay component uses dialog role and since any attribute is passed to the root element you may define attributes like aria-label or aria-labelledby to describe the popup contents. In addition aria-modal is added since focus is kept within the popup.

It is recommended to use a trigger component that can be accessed with keyboard such as a button, if not adding tabIndex would be necessary. Overlay adds aria-expanded state attribute and aria-controls to the trigger so that the relation between the trigger and the popup is defined.

Overlay Keyboard Support

When the popup gets opened, the first focusable element receives the focus and this can be customized by adding autofocus to an element within the popup.

KeyFunction
tabMoves focus to the next the focusable element within the popup.
shift + tabMoves focus to the previous the focusable element within the popup.
escapeCloses the popup and moves focus to the trigger.

Close Button Keyboard Support

KeyFunction
enterCloses the popup and moves focus to the trigger.
spaceCloses the popup and moves focus to the trigger.
PrimeNG 17.15.0 by PrimeTek