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

flexibleConnectedTo
Creates a flexible position strategy.
Parameters
origin `FlexibleConnectedPositionStrategyOrigin`	Origin relative to which to position the overlay.
Returns
`FlexibleConnectedPositionStrategy`

global
Creates a global position strategy.
Returns
`GlobalPositionStrategy`

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

`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] [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 FlexibleConnectedPositionStrategy.

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

Exported as: cdkConnectedOverlay

Properties

Name	Description
@Input('cdkConnectedOverlayBackdropClass') `backdropClass: string`	The custom class to be set on the backdrop element.
@Input('cdkConnectedOverlayFlexibleDimensions') `flexibleDimensions: boolean`	Whether the overlay's width and height can be constrained to fit within the viewport.
@Input('cdkConnectedOverlayGrowAfterOpen') `growAfterOpen: boolean`	Whether the overlay can grow after the initial open when flexible positioning is turned on.
@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('cdkConnectedOverlayPanelClass') `panelClass: string \| string[]`	The custom class to add to the overlay pane element.
@Input('cdkConnectedOverlayPositions') `positions: ConnectedPosition[]`	Registered connected position pairs.
@Input('cdkConnectedOverlayPush') `push: boolean`	Whether the overlay can be pushed on-screen if none of the provided positions fit.
@Input('cdkConnectedOverlayScrollStrategy') `scrollStrategy: ScrollStrategy`	Strategy to be used when handling scroll events while the overlay is open.
@Input('cdkConnectedOverlayViewportMargin') `viewportMargin: number`	Margin between the overlay and the viewport edges.
@Input('cdkConnectedOverlayWidth') `width: number \| string`	The width of the overlay panel.
@Output() `attach: EventEmitter<void>`	Event emitted when the overlay has been attached.
@Output() `backdropClick: EventEmitter<MouseEvent>`	Event emitted when the backdrop is clicked.
@Output() `detach: EventEmitter<void>`	Event emitted when the overlay has been detached.
@Output() `overlayKeydown: EventEmitter<KeyboardEvent>`	Emits when there are keyboard events that are targeted at the overlay.
@Output() `positionChange: EventEmitter<ConnectedOverlayPositionChange>`	Event emitted when the position has changed.
`dir: Direction`	The element's layout direction.
`overlayRef: OverlayRef`	The associated overlay reference.

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.
`hostElement: HTMLElement`	Wrapper around the panel element. Can be used for advanced positioning where a wrapper with specific styling is required around the overlay pane.
`overlayElement: HTMLElement`	The overlay's HTML element

Methods

addPanelClass
Add a CSS class or an array of classes to the overlay pane.
Parameters
classes `string \| string[]`

attach
Parameters
portal `any`
Returns
`any`

attach
Parameters
portal `TemplatePortal<T>`
Returns
`EmbeddedViewRef<T>`

attach
Parameters
portal `ComponentPortal<T>`
Returns
`ComponentRef<T>`

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 current overlay configuration, which is immutable.
Returns
`OverlayConfig`

getDirection
Returns the layout direction of the overlay panel.
Returns
`Direction`

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

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

removePanelClass
Remove a CSS class or an array of classes from the overlay pane.
Parameters
classes `string \| string[]`

setDirection
Sets the LTR/RTL direction for the overlay.
Parameters
dir `"ltr" \| "rtl" \| Directionality`

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

updatePositionStrategy
Switches to a new position strategy and updates the overlay position.
Parameters
strategy `PositionStrategy`

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 `OverlayReference`

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.

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

Deprecated

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 `OverlayReference`

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<any>`	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[]`

`FlexibleConnectedPositionStrategy`

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
`positionChanges: Observable<ConnectedOverlayPositionChange>`	Observable sequence of position changes.
`positions:`	Ordered list of preferred positions, from most to least desirable.

Methods

attach
Attaches this position strategy to an overlay.
Parameters
overlayRef `OverlayReference`

detach

dispose
Cleanup after the element gets destroyed.

reapplyLastPosition
This re-aligns 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, relative to which to position the overlay. Using an element origin is useful for building components that need to be positioned relatively to a trigger (e.g. dropdown menus or tooltips), whereas using a point can be used for cases like contextual menus which open relative to the user's pointer.
Parameters
origin `FlexibleConnectedPositionStrategyOrigin`	Reference to the new origin.
Returns
`this`

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

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

withFlexibleDimensions
Sets whether the overlay's width and height can be constrained to fit within the viewport.
Parameters
flexibleDimensions `boolean = true`
Returns
`this`

withGrowAfterOpen
Sets whether the overlay can grow after the initial open via flexible width/height.
Parameters
growAfterOpen `boolean = true`
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 = true`	Whether the overlay should locked in.
Returns
`this`

withPositions
Adds new preferred positions.
Parameters
positions `ConnectedPosition[]`	List of positions options for this overlay.
Returns
`this`

withPush
Sets whether the overlay can be pushed on-screen if none of the provided positions fit.
Parameters
canPush `boolean = true`
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[]`
Returns
`this`

withTransformOriginOn
Configures that the position strategy should set a `transform-origin` on some elements inside the overlay, depending on the current position that is being applied. This is useful for the cases where the origin of an animation can change depending on the alignment of the overlay.
Parameters
selector `string`	CSS selector that will be used to find the target elements onto which to set the transform origin.
Returns
`this`

withViewportMargin
Sets a minimum distance the overlay may be positioned to the edge of the viewport.
Parameters
margin `number`	Required margin between the overlay and the viewport edge in pixels.
Returns
`this`

`OverlayConfig`

Initial configuration used when creating an overlay.

Properties

Name	Description
`backdropClass: string \| string[]`	Custom class to add to the backdrop
`direction: Direction \| Directionality`	Direction of the text in the overlay panel. If a `Directionality` instance is passed in, the overlay will handle changes to its value automatically.
`disposeOnNavigation: boolean`	Whether the overlay should be disposed of when the user goes backwards/forwards in history. Note that this usually doesn't include clicking on links (unless the user is using the `HashLocationStrategy`).
`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`	Offset along the X axis.
`offsetY: number`	Offset along the Y axis.
`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'.
`panelClass: string \| string[]`	Class(es) to be applied to the panel while this position is active.

`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 `OverlayReference`

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 `OverlayReference`

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.

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
overlayRef `OverlayReference`

detach
Called when the overlay is detached.

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

`ConnectedPosition`

A connected position as specified by the user.

Properties

Name	Description
`offsetX: number`
`offsetY: number`
`originX: 'start' \| 'center' \| 'end'`
`originY: 'top' \| 'center' \| 'bottom'`
`overlayX: 'start' \| 'center' \| 'end'`
`overlayY: 'top' \| 'center' \| 'bottom'`
`panelClass: string \| string[]`
`weight: number`

`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: OverlayReference) => 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).

`RepositionScrollStrategyConfig`

Config options for the RepositionScrollStrategy.

Properties

Name	Description
`autoClose: boolean`	Whether to close the overlay once the user has scrolled away completely.
`scrollThrottle: number`	Time in milliseconds to throttle the scroll events.

Type aliases

`HorizontalConnectionPos`

type HorizontalConnectionPos = 'start' | 'center' | 'end';

`VerticalConnectionPos`

Vertical dimension of a connection point on the perimeter of the origin or overlay element.

type VerticalConnectionPos = 'top' | 'center' | 'bottom';

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 Classes

link OverlayRef

Properties

Methods

link GlobalPositionStrategy

Methods

link ConnectedPositionStrategy

Properties

Methods

link FlexibleConnectedPositionStrategy

Properties

Methods

link OverlayConfig

Properties

link ConnectionPositionPair

Properties

link ConnectedOverlayPositionChange

Properties

link RepositionScrollStrategy

Methods

link CloseScrollStrategy

Methods

link NoopScrollStrategy

Methods

link BlockScrollStrategy

Methods

link Interfaces

link OverlaySizeConfig

Properties

link PositionStrategy

Methods

link ConnectedPosition

Properties

link OriginConnectionPosition

Properties

link OverlayConnectionPosition

Properties

link ScrollStrategy

Properties

link RepositionScrollStrategyConfig

Properties

link Type aliases

link HorizontalConnectionPos

link VerticalConnectionPos

Services

`Overlay`

`OverlayContainer`

`FullscreenOverlayContainer` extends OverlayContainer

`OverlayKeyboardDispatcher`

`OverlayPositionBuilder`

`ScrollStrategyOptions`

Directives

`CdkOverlayOrigin`

`CdkConnectedOverlay`

Classes

`OverlayRef`

`GlobalPositionStrategy`

`ConnectedPositionStrategy`

`FlexibleConnectedPositionStrategy`

`OverlayConfig`

`ConnectionPositionPair`

`ConnectedOverlayPositionChange`

`RepositionScrollStrategy`

`CloseScrollStrategy`

`NoopScrollStrategy`

`BlockScrollStrategy`

Interfaces

`OverlaySizeConfig`

`PositionStrategy`

`ConnectedPosition`

`OriginConnectionPosition`

`OverlayConnectionPosition`

`ScrollStrategy`

`RepositionScrollStrategyConfig`

Type aliases

`HorizontalConnectionPos`

`VerticalConnectionPos`