Overlay

API reference for Angular CDK overlay

import {OverlayModule} from '@angular/cdk/overlay';

Services

`Overlay`

Service to create Overlays. Overlays are dynamically added pieces of floating UI, meant to be used as a low-level building block for other components. Dialogs, tooltips, menus, selects, etc. can all be built using overlays. The service should primarily be used by authors of re-usable components rather than developers building end-user applications.

An overlay is a PortalOutlet, so any kind of Portal can be loaded into one.

Properties

Name	Description
`scrollStrategies: ScrollStrategyOptions`	Scrolling strategies that can be used when creating an overlay.

Methods

create
Creates an overlay.
Parameters
config? `OverlayConfig`	Configuration applied to the overlay.
Returns
`OverlayRef`	Reference to the created overlay.

position

position
Gets a position builder that can be used, via fluent API, to construct and configure a position strategy.
`OverlayPositionBuilder`	An overlay position builder.

Gets a position builder that can be used, via fluent API, to construct and configure a position strategy.

Returns

OverlayPositionBuilder

An overlay position builder.

`OverlayContainer`

Container inside which all overlays will render.

Methods

getContainerElement

getContainerElement
This method returns the overlay container element. It will lazily create the element the first time it is called to facilitate using the container in non-browser environments.
`HTMLElement`	the container element

This method returns the overlay container element. It will lazily create the element the first time it is called to facilitate using the container in non-browser environments.

Returns

HTMLElement

the container element

`FullscreenOverlayContainer` extends OverlayContainer

Alternative to OverlayContainer that supports correct displaying of overlay elements in Fullscreen mode https://developer.mozilla.org/en-US/docs/Web/API/Element/requestFullScreen

Should be provided in the root component.

Methods

getContainerElement

getContainerElement
This method returns the overlay container element. It will lazily create the element the first time it is called to facilitate using the container in non-browser environments.
`HTMLElement`	the container element

This method returns the overlay container element. It will lazily create the element the first time it is called to facilitate using the container in non-browser environments.

Returns

HTMLElement

the container element

getFullscreenElement
When the page is put into fullscreen mode, a specific element is specified. Only that element and its children are visible when in fullscreen mode.
Returns
`Element`

`OverlayKeyboardDispatcher`

Service for dispatching keyboard events that land on the body to appropriate overlay ref, if any. It maintains a list of attached overlays to determine best suited overlay based on event target and order of overlay opens.

Methods

add
Add a new overlay to the list of attached overlay refs.
Parameters
overlayRef `OverlayRef`

remove
Remove an overlay from the list of attached overlay refs.
Parameters
overlayRef `OverlayRef`

`OverlayPositionBuilder`

Builder for overlay position strategy.

Methods

connectedTo
Creates a relative position strategy.
Parameters
elementRef `ElementRef`
originPos `OriginConnectionPosition`
overlayPos `OverlayConnectionPosition`
Returns
`ConnectedPositionStrategy`

global
Creates a global position strategy.
Returns
`GlobalPositionStrategy`

`ScrollStrategyOptions`

Options for how an overlay will handle scrolling.

Users can provide a custom value for ScrollStrategyOptions to replace the default behaviors. This class primarily acts as a factory for ScrollStrategy instances.

Properties

Name	Description
`block: () => new BlockScrollStrategy(this._viewportRuler, this._document)`	Block scrolling.
`close: (config?: CloseScrollStrategyConfig) => new CloseScrollStrategy(this._scrollDispatcher, this._ngZone, this._viewportRuler, config)`	Close the overlay as soon as the user scrolls.
`noop: () => new NoopScrollStrategy()`	Do nothing on scroll.
`reposition: (config?: RepositionScrollStrategyConfig) => new RepositionScrollStrategy(this._scrollDispatcher, this._viewportRuler, this._ngZone, config)`	Update the overlay's position on scroll.

Directives

`CdkOverlayOrigin`

Directive applied to an element to make it usable as an origin for an Overlay using a ConnectedPositionStrategy.

Selector: [cdk-overlay-origin] [cdkOverlayOrigin]

Exported as: cdkOverlayOrigin

Properties

Name	Description
`elementRef: ElementRef`	Reference to the element on which the directive is applied.

`CdkConnectedOverlay`

Directive to facilitate declarative creation of an Overlay using a ConnectedPositionStrategy.

Selector: [cdk-connected-overlay] [cdkConnectedOverlay]

Exported as: cdkConnectedOverlay

Properties

Name	Description
@Input('cdkConnectedOverlayBackdropClass') `backdropClass: string`	The custom class to be set on the backdrop element.
@Input('cdkConnectedOverlayHasBackdrop') `hasBackdrop: any`	Whether or not the overlay should attach a backdrop.
@Input('cdkConnectedOverlayHeight') `height: number \| string`	The height of the overlay panel.
@Input('cdkConnectedOverlayLockPosition') `lockPosition: any`	Whether or not the overlay should be locked when scrolling.
@Input('cdkConnectedOverlayMinHeight') `minHeight: number \| string`	The min height of the overlay panel.
@Input('cdkConnectedOverlayMinWidth') `minWidth: number \| string`	The min width of the overlay panel.
@Input('cdkConnectedOverlayOffsetX') `offsetX: number`	The offset in pixels for the overlay connection point on the x-axis
@Input('cdkConnectedOverlayOffsetY') `offsetY: number`	The offset in pixels for the overlay connection point on the y-axis
@Input('cdkConnectedOverlayOpen') `open: boolean`	Whether the overlay is open.
@Input('cdkConnectedOverlayOrigin') `origin: CdkOverlayOrigin`	Origin for the connected overlay.
@Input('cdkConnectedOverlayPositions') `positions: ConnectionPositionPair[]`	Registered connected position pairs.
@Input('cdkConnectedOverlayScrollStrategy') `scrollStrategy: ScrollStrategy`	Strategy to be used when handling scroll events while the overlay is open.
@Input('cdkConnectedOverlayWidth') `width: number \| string`	The width of the overlay panel.
@Output() `attach: new EventEmitter<void>()`	Event emitted when the overlay has been attached.
@Output() `backdropClick: new EventEmitter<MouseEvent>()`	Event emitted when the backdrop is clicked.
@Output() `detach: new EventEmitter<void>()`	Event emitted when the overlay has been detached.
@Output() `positionChange: new EventEmitter<ConnectedOverlayPositionChange>()`	Event emitted when the position has changed.
`dir: Direction`	The element's layout direction.
`overlayRef: OverlayRef`	The associated overlay reference.

Additional classes

`OverlayRef`

Reference to an overlay that has been created with the Overlay service. Used to manipulate or dispose of said overlay.

Properties

Name	Description
`backdropElement: HTMLElement \| null`	The overlay's backdrop HTML element.
`overlayElement: HTMLElement`	The overlay's HTML element

Methods

attach
Attaches content, given via a Portal, to the overlay. If the overlay is configured to have a backdrop, it will be created.
Parameters
portal `Portal<any>`	Portal instance to which to attach the overlay.
Returns
`any`	The portal attachment result.

attachments
Gets an observable that emits when the overlay has been attached.
Returns
`Observable<void>`

backdropClick
Gets an observable that emits when the backdrop has been clicked.
Returns
`Observable<MouseEvent>`

detach

detach
Detaches an overlay from a portal.
`any`	The portal detachment result.

Detaches an overlay from a portal.

Returns

any

The portal detachment result.

detachBackdrop
Detaches the backdrop (if any) associated with the overlay.

detachments
Gets an observable that emits when the overlay has been detached.
Returns
`Observable<void>`

dispose
Cleans up the overlay from the DOM.

getConfig
Gets the the current overlay configuration, which is immutable.
Returns
`OverlayConfig`

hasAttached
Whether the overlay has attached content.
Returns
`boolean`

keydownEvents
Gets an observable of keydown events targeted to this overlay.
Returns
`Observable<KeyboardEvent>`

setDirection
Sets the LTR/RTL direction for the overlay.
Parameters
dir `Direction`

updatePosition
Updates the position of the overlay based on the position strategy.

updateSize
Update the size properties of the overlay.
Parameters
sizeConfig `OverlaySizeConfig`

`GlobalPositionStrategy`

A strategy for positioning overlays. Using this strategy, an overlay is given an explicit position relative to the browser's viewport. We use flexbox, instead of transforms, in order to avoid issues with subpixel rendering which can cause the element to become blurry.

Methods

attach
Parameters
overlayRef `OverlayRef`

bottom
Sets the bottom position of the overlay. Clears any previously set vertical position.
Parameters
value `string = ''`	New bottom offset.
Returns
`this`

centerHorizontally
Centers the overlay horizontally with an optional offset. Clears any previously set horizontal position.
Parameters
offset `string = ''`	Overlay offset from the horizontal center.
Returns
`this`

centerVertically
Centers the overlay vertically with an optional offset. Clears any previously set vertical position.
Parameters
offset `string = ''`	Overlay offset from the vertical center.
Returns
`this`

detach
Called when the overlay is detached.

dispose
Removes the wrapper element from the DOM.

left
Sets the left position of the overlay. Clears any previously set horizontal position.
Parameters
value `string = ''`	New left offset.
Returns
`this`

right
Sets the right position of the overlay. Clears any previously set horizontal position.
Parameters
value `string = ''`	New right offset.
Returns
`this`

top
Sets the top position of the overlay. Clears any previously set vertical position.
Parameters
value `string = ''`	New top offset.
Returns
`this`

Deprecated height
Sets the overlay height and clears any previously set height.
Parameters
value `string = ''`	New height for the overlay
Returns
`this`

Deprecated width
Sets the overlay width and clears any previously set width.
Parameters
value `string = ''`	New width for the overlay
Returns
`this`

`ConnectedPositionStrategy`

A strategy for positioning overlays. Using this strategy, an overlay is given an implicit position relative some origin element. The relative position is defined in terms of a point on the origin element that is connected to a point on the overlay element. For example, a basic dropdown is connecting the bottom-left corner of the origin to the top-left corner of the overlay.

Properties

Name	Description
`onPositionChange: Observable<ConnectedOverlayPositionChange>`	Emits an event when the connection point changes.
`positions: ConnectionPositionPair[]`	Ordered list of preferred positions, from most to least desirable.

Methods

attach
Attach this position strategy to an overlay.
Parameters
overlayRef `OverlayRef`

dispose
Disposes all resources used by the position strategy.

recalculateLastPosition
Re-positions the overlay element with the trigger in its last calculated position, even if a position higher in the "preferred positions" list would now fit. This allows one to re-align the panel without changing the orientation of the panel.

setOrigin
Sets the origin element, relative to which to position the overlay.
Parameters
origin `ElementRef`	Reference to the new origin element.
Returns
`this`

withDirection
Sets the layout direction so the overlay's position can be adjusted to match.
Parameters
dir `'ltr' \| 'rtl'`	New layout direction.
Returns
`this`

withFallbackPosition
Adds a new preferred fallback position.
Parameters
originPos `OriginConnectionPosition`
overlayPos `OverlayConnectionPosition`
offsetX? `number`
offsetY? `number`
Returns
`this`

withLockedPosition
Sets whether the overlay's position should be locked in after it is positioned initially. When an overlay is locked in, it won't attempt to reposition itself when the position is re-applied (e.g. when the user scrolls away).
Parameters
isLocked `boolean`	Whether the overlay should locked in.
Returns
`this`

withOffsetX
Sets an offset for the overlay's connection point on the x-axis
Parameters
offset `number`	New offset in the X axis.
Returns
`this`

withOffsetY
Sets an offset for the overlay's connection point on the y-axis
Parameters
offset `number`	New offset in the Y axis.
Returns
`this`

withPositions
Overwrites the current set of positions with an array of new ones.
Parameters
positions `ConnectionPositionPair[]`	Position pairs to be set on the strategy.
Returns
`this`

withScrollableContainers
Sets the list of Scrollable containers that host the origin element so that on reposition we can evaluate if it or the overlay has been clipped or outside view. Every Scrollable must be an ancestor element of the strategy's origin element.
Parameters
scrollables `CdkScrollable[]`

`OverlayConfig`

Initial configuration used when creating an overlay.

Properties

Name	Description
`backdropClass: string`	Custom class to add to the backdrop
`direction: Direction`	The direction of the text in the overlay panel.
`hasBackdrop: boolean`	Whether the overlay has a backdrop.
`height: number \| string`	The height of the overlay panel. If a number is provided, pixel units are assumed.
`maxHeight: number \| string`	The max-height of the overlay panel. If a number is provided, pixel units are assumed.
`maxWidth: number \| string`	The max-width of the overlay panel. If a number is provided, pixel units are assumed.
`minHeight: number \| string`	The min-height of the overlay panel. If a number is provided, pixel units are assumed.
`minWidth: number \| string`	The min-width of the overlay panel. If a number is provided, pixel units are assumed.
`panelClass: string \| string[]`	Custom class to add to the overlay pane.
`positionStrategy: PositionStrategy`	Strategy with which to position the overlay.
`scrollStrategy: ScrollStrategy`	Strategy to be used when handling scroll events while the overlay is open.
`width: number \| string`	The width of the overlay panel. If a number is provided, pixel units are assumed.

`ConnectionPositionPair`

The points of the origin element and the overlay element to connect.

Properties

Name	Description
`offsetX: number`
`offsetY: number`
`originX: HorizontalConnectionPos`	X-axis attachment point for connected overlay origin. Can be 'start', 'end', or 'center'.
`originY: VerticalConnectionPos`	Y-axis attachment point for connected overlay origin. Can be 'top', 'bottom', or 'center'.
`overlayX: HorizontalConnectionPos`	X-axis attachment point for connected overlay. Can be 'start', 'end', or 'center'.
`overlayY: VerticalConnectionPos`	Y-axis attachment point for connected overlay. Can be 'top', 'bottom', or 'center'.

`ConnectedOverlayPositionChange`

The change event emitted by the strategy when a fallback position is used.

Properties

Name	Description
`connectionPair: ConnectionPositionPair`	The position used as a result of this change.

`RepositionScrollStrategy`

Strategy that will update the element position as the user is scrolling.

Methods

attach
Attaches this scroll strategy to an overlay.
Parameters
overlayRef `OverlayRef`

disable
Disables repositioning of the attached overlay on scroll.

enable
Enables repositioning of the attached overlay on scroll.

`CloseScrollStrategy`

Strategy that will close the overlay as soon as the user starts scrolling.

Methods

attach
Attaches this scroll strategy to an overlay.
Parameters
overlayRef `OverlayRef`

disable
Disables the closing the attached overlay on scroll.

enable
Enables the closing of the attached overlay on scroll.

`NoopScrollStrategy`

Scroll strategy that doesn't do anything.

Methods

attach
Does nothing, as this scroll strategy is a no-op.

disable
Does nothing, as this scroll strategy is a no-op.

enable
Does nothing, as this scroll strategy is a no-op.

`BlockScrollStrategy`

Strategy that will prevent the user from scrolling while the overlay is visible.

Methods

attach
Attaches this scroll strategy to an overlay.

disable
Unblocks page-level scroll while the attached overlay is open.

enable
Blocks page-level scroll while the attached overlay is open.

Additional interfaces

`OverlaySizeConfig`

Size properties for an overlay.

Properties

Name	Description
`height: number \| string`
`maxHeight: number \| string`
`maxWidth: number \| string`
`minHeight: number \| string`
`minWidth: number \| string`
`width: number \| string`

`PositionStrategy`

Strategy for setting the position on an overlay.

Methods

apply
Updates the position of the overlay element.

attach
Attaches this position strategy to an overlay.
Parameters
overlay `OverlayRef`

detach
Called when the overlay is detached.

dispose
Cleans up any DOM modifications made by the position strategy, if necessary.

`OriginConnectionPosition`

A connection point on the origin element.

Properties

Name	Description
`originX: HorizontalConnectionPos`
`originY: VerticalConnectionPos`

`OverlayConnectionPosition`

A connection point on the overlay element.

Properties

Name	Description
`overlayX: HorizontalConnectionPos`
`overlayY: VerticalConnectionPos`

`ScrollStrategy`

Describes a strategy that will be used by an overlay to handle scroll events while it is open.

Properties

Name	Description
`attach: (overlayRef: OverlayRef) => void`	Attaches this `ScrollStrategy` to an overlay.
`disable: () => void`	Disable this scroll strategy (called when the attached overlay is detached from a portal).
`enable: () => void`	Enable this scroll strategy (called when the attached overlay is attached to a portal).

Contents

Name	Description
`height: number \| string`
`maxHeight: number \| string`
`maxWidth: number \| string`
`minHeight: number \| string`
`minWidth: number \| string`
`width: number \| string`

Overlay

API reference for Angular CDK overlay

link Services

link Overlay

Properties

Methods

link OverlayContainer

Methods

link FullscreenOverlayContainer extends OverlayContainer

Methods

link OverlayKeyboardDispatcher

Methods

link OverlayPositionBuilder

Methods

link ScrollStrategyOptions

Properties

link Directives

link CdkOverlayOrigin

Properties

link CdkConnectedOverlay

Properties

link Additional classes

link OverlayRef

Properties

Methods

link GlobalPositionStrategy

Methods

link ConnectedPositionStrategy

Properties

Methods

link OverlayConfig

Properties

link ConnectionPositionPair

Properties

link ConnectedOverlayPositionChange

Properties

link RepositionScrollStrategy

Methods

link CloseScrollStrategy

Methods

link NoopScrollStrategy

Methods

link BlockScrollStrategy

Methods

link Additional interfaces

link OverlaySizeConfig

Properties

link PositionStrategy

Methods

link OriginConnectionPosition

Properties

link OverlayConnectionPosition

Properties

link ScrollStrategy

Properties

Services

`Overlay`

`OverlayContainer`

`FullscreenOverlayContainer` extends OverlayContainer

`OverlayKeyboardDispatcher`

`OverlayPositionBuilder`

`ScrollStrategyOptions`

Directives

`CdkOverlayOrigin`

`CdkConnectedOverlay`

Additional classes

`OverlayRef`

`GlobalPositionStrategy`

`ConnectedPositionStrategy`

`OverlayConfig`

`ConnectionPositionPair`

`ConnectedOverlayPositionChange`

`RepositionScrollStrategy`

`CloseScrollStrategy`

`NoopScrollStrategy`

`BlockScrollStrategy`

Additional interfaces

`OverlaySizeConfig`

`PositionStrategy`

`OriginConnectionPosition`

`OverlayConnectionPosition`

`ScrollStrategy`