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 |
---|---|
|
Methods
create | |
---|---|
Creates an overlay. |
|
Parameters | |
config? OverlayConfig
|
Configuration applied to the overlay. |
Returns | |
OverlayRef
|
Reference to the created overlay. |
position | |
---|---|
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 | |
---|---|
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 | |
---|---|
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
|
|
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
|
|
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 scrolling. |
|
Close the overlay as soon as the user scrolls. |
|
Do nothing on scroll. |
|
Update the overlay's position on scroll. |
OverlayOutsideClickDispatcher
Service for dispatching mouse click 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
|
|
detach | |
---|---|
Detaches the global keyboard event listener. |
remove | |
---|---|
Remove an overlay from the list of attached overlay refs. |
|
Parameters | |
overlayRef OverlayRef
|
|
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
|
|
detach | |
---|---|
Detaches the global keyboard event listener. |
remove | |
---|---|
Remove an overlay from the list of attached overlay refs. |
|
Parameters | |
overlayRef OverlayRef
|
|
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: cdkOverlayOriginProperties
Name | Description |
---|---|
|
CdkConnectedOverlay
Directive to facilitate declarative creation of an Overlay using a FlexibleConnectedPositionStrategy.
Selector: [cdk-connected-overlay] [connected-overlay] [cdkConnectedOverlay]
Exported as: cdkConnectedOverlayProperties
Name | Description |
---|---|
@Input('cdkConnectedOverlayBackdropClass')
|
The custom class to be set on the backdrop element. |
@Input('cdkConnectedOverlayDisableClose')
|
Whether the overlay can be closed by user interaction. |
@Input({ alias: 'cdkConnectedOverlayDisposeOnNavigation', transform: booleanAttribute })
|
Whether the overlay should be disposed of when the user goes backwards/forwards in history. |
@Input({ alias: 'cdkConnectedOverlayFlexibleDimensions', transform: booleanAttribute })
|
Whether the overlay's width and height can be constrained to fit within the viewport. |
@Input({ alias: 'cdkConnectedOverlayGrowAfterOpen', transform: booleanAttribute })
|
Whether the overlay can grow after the initial open when flexible positioning is turned on. |
@Input({ alias: 'cdkConnectedOverlayHasBackdrop', transform: booleanAttribute })
|
Whether or not the overlay should attach a backdrop. |
@Input('cdkConnectedOverlayHeight')
|
The height of the overlay panel. |
@Input({ alias: 'cdkConnectedOverlayLockPosition', transform: booleanAttribute })
|
Whether or not the overlay should be locked when scrolling. |
@Input('cdkConnectedOverlayMinHeight')
|
The min height of the overlay panel. |
@Input('cdkConnectedOverlayMinWidth')
|
The min width of the overlay panel. |
@Input('cdkConnectedOverlayOffsetX')
|
The offset in pixels for the overlay connection point on the x-axis |
@Input('cdkConnectedOverlayOffsetY')
|
The offset in pixels for the overlay connection point on the y-axis |
@Input('cdkConnectedOverlayOpen')
|
Whether the overlay is open. |
@Input('cdkConnectedOverlayOrigin')
|
Origin for the connected overlay. |
@Input('cdkConnectedOverlayPanelClass')
|
The custom class to add to the overlay pane element. |
@Input('cdkConnectedOverlayPositionStrategy')
|
This input overrides the positions input if specified. It lets users pass in arbitrary positioning strategies. |
@Input('cdkConnectedOverlayPositions')
|
Registered connected position pairs. |
@Input({ alias: 'cdkConnectedOverlayPush', transform: booleanAttribute })
|
Whether the overlay can be pushed on-screen if none of the provided positions fit. |
@Input('cdkConnectedOverlayScrollStrategy')
|
Strategy to be used when handling scroll events while the overlay is open. |
@Input('cdkConnectedOverlayTransformOriginOn')
|
CSS selector which to set the transform origin. |
@Input('cdkConnectedOverlayViewportMargin')
|
Margin between the overlay and the viewport edges. |
@Input('cdkConnectedOverlayWidth')
|
The width of the overlay panel. |
@Output()
|
Event emitted when the overlay has been attached. |
@Output()
|
Event emitted when the backdrop is clicked. |
@Output()
|
Event emitted when the overlay has been detached. |
@Output()
|
Emits when there are keyboard events that are targeted at the overlay. |
@Output()
|
Emits when there are mouse outside click events that are targeted at the overlay. |
@Output()
|
Event emitted when the position has changed. |
|
The element's layout direction. |
|
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 |
---|---|
|
The overlay's backdrop HTML element. |
|
Wrapper around the panel element. Can be used for advanced positioning where a wrapper with specific styling is required around the overlay pane. |
|
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 ComponentPortal<T>
|
|
Returns | |
ComponentRef<T>
|
|
attach | |
---|---|
Parameters | |
portal TemplatePortal<T>
|
|
Returns | |
EmbeddedViewRef<T>
|
|
attach | |
---|---|
Parameters | |
portal any
|
|
Returns | |
any
|
|
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 | |
---|---|
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>
|
|
outsidePointerEvents | |
---|---|
Gets an observable of pointer events targeted outside this overlay. |
|
Returns | |
Observable<MouseEvent>
|
|
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 Directionality | Direction
|
|
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
|
|
updateScrollStrategy | |
---|---|
Switches to a new scroll strategy. |
|
Parameters | |
strategy ScrollStrategy
|
|
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
|
|
end | |
---|---|
Sets the overlay to the end of the viewport, depending on the overlay direction. This will be to the right in LTR layouts and to the left in RTL. |
|
Parameters | |
offset
|
Offset from the edge of the screen. |
value string = ''
|
|
Returns | |
this
|
|
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
|
|
start | |
---|---|
Sets the overlay to the start of the viewport, depending on the overlay direction. This will be to the left in LTR layouts and to the right in RTL. |
|
Parameters | |
offset
|
Offset from the edge of the screen. |
value string = ''
|
|
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
|
|
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 |
---|---|
|
Observable sequence of position changes. |
|
Ordered list of preferred positions, from most to least desirable. |
Methods
attach | |
---|---|
Attaches this position strategy to an overlay. |
|
Parameters | |
overlayRef OverlayRef
|
|
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 |
|
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 |
---|---|
|
Custom class to add to the backdrop |
|
Direction of the text in the overlay panel. If a |
|
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 |
|
Whether the overlay has a backdrop. |
|
The height of the overlay panel. If a number is provided, pixel units are assumed. |
|
The max-height of the overlay panel. If a number is provided, pixel units are assumed. |
|
The max-width of the overlay panel. If a number is provided, pixel units are assumed. |
|
The min-height of the overlay panel. If a number is provided, pixel units are assumed. |
|
The min-width of the overlay panel. If a number is provided, pixel units are assumed. |
|
Custom class to add to the overlay pane. |
|
Strategy with which to position the overlay. |
|
Strategy to be used when handling scroll events while the overlay is open. |
|
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 |
---|---|
|
Offset along the X axis. |
|
Offset along the Y axis. |
|
X-axis attachment point for connected overlay origin. Can be 'start', 'end', or 'center'. |
|
Y-axis attachment point for connected overlay origin. Can be 'top', 'bottom', or 'center'. |
|
X-axis attachment point for connected overlay. Can be 'start', 'end', or 'center'. |
|
Y-axis attachment point for connected overlay. Can be 'top', 'bottom', or 'center'. |
|
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 |
---|---|
|
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
|
|
detach |
---|
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
|
|
detach |
---|
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 |
---|---|
|
|
|
|
|
|
|
|
|
|
|
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 OverlayRef
|
|
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 |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
OriginConnectionPosition
A connection point on the origin element.
Properties
Name | Description |
---|---|
|
|
|
OverlayConnectionPosition
A connection point on the overlay element.
Properties
Name | Description |
---|---|
|
|
|
ScrollStrategy
Describes a strategy that will be used by an overlay to handle scroll events while it is open.
Properties
Name | Description |
---|---|
|
Attaches this |
|
Detaches the scroll strategy from the current overlay. |
|
Disable this scroll strategy (called when the attached overlay is detached from a portal). |
|
Enable this scroll strategy (called when the attached overlay is attached to a portal). |
RepositionScrollStrategyConfig
Config options for the RepositionScrollStrategy.
Properties
Name | Description |
---|---|
|
Whether to close the overlay once the user has scrolled away completely. |
|
Time in milliseconds to throttle the scroll events. |
Type aliases
FlexibleConnectedPositionStrategyOrigin
Possible values that can be set as the origin of a FlexibleConnectedPositionStrategy.
type FlexibleConnectedPositionStrategyOrigin = ElementRef | Element | (Point & {
width?: number;
height?: number;
});
HorizontalConnectionPos
Horizontal dimension of a connection point on the perimeter of the origin or overlay element.
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';
Constants
STANDARD_DROPDOWN_ADJACENT_POSITIONS
const STANDARD_DROPDOWN_ADJACENT_POSITIONS: ConnectedPosition[];
STANDARD_DROPDOWN_BELOW_POSITIONS
const STANDARD_DROPDOWN_BELOW_POSITIONS: ConnectedPosition[];