chore(overlay): fix docs again again

wnvko · wnvko · commit 32e9669f5118 · 2026-03-12T13:01:34.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,10 +7,9 @@ All notable changes for each version of this project will be documented in this
 ### New Features
 
 - `IgxOverlayService`
-    - The overlay service now always renders content in place using the HTML Popover API, eliminating the need for outlet containers.
-
-    - **Deprecation** - The `outlet` property in `OverlaySettings`, `IgxOverlayOutletDirective`, and `igxToggleOutlet` input on `IgxToggleActionDirective` are all deprecated. The overlay service now always renders content in place using the HTML Popover API. These will be removed in a future version.
+    - The overlay service now integrates the HTML Popover API and prefers rendering content in place / in the top layer, significantly reducing the need for outlet containers. When configured, `OverlaySettings.outlet` is still honored, and overlays may also fall back to being appended to `document.body` when required.
 
+    - **Deprecation** - The `outlet` property in `OverlaySettings`, `IgxOverlayOutletDirective`, and `igxToggleOutlet` input on `IgxToggleActionDirective` are deprecated and will be removed in a future version. They remain functional in this release for backward compatibility, but new code should rely on the default in-place / top-layer rendering behavior instead of custom outlet containers.
 ## 21.1.0
 
 ### New Features
diff --git a/projects/igniteui-angular/core/src/services/overlay/position/README.md b/projects/igniteui-angular/core/src/services/overlay/position/README.md
@@ -7,7 +7,7 @@ Position strategies determine where to display the component in the provided Igx
 |:---------------------------|:-------------------------|
 | HorizontalAlignment.Center | VerticalAlignment.Middle |
 
-2) **Container** - Positions the element inside the containing outlet based on the directions passed in through PositionSettings. These are Top/Middle/Bottom for verticalDirection and Left/Center/Right for horizontalDirection. **Note:** The `outlet` property in `OverlaySettings` is deprecated and no longer has any effect. The overlay service now always renders content in place using the HTML Popover API. Defaults to:
+2) **Container** - Positions the element inside the containing outlet based on the directions passed in through PositionSettings. These are Top/Middle/Bottom for verticalDirection and Left/Center/Right for horizontalDirection. **Note:** The `outlet` property in `OverlaySettings` is still supported and used by the overlay service when provided but will be removed in a future version. Avoid using this property in new code and prefer the default in-place rendering with the HTML Popover API. Defaults to:
 
 | horizontalDirection        | verticalDirection        |
 |:---------------------------|:-------------------------|
diff --git a/projects/igniteui-angular/core/src/services/overlay/utilities.ts b/projects/igniteui-angular/core/src/services/overlay/utilities.ts
@@ -132,9 +132,9 @@ export interface OverlaySettings {
     closeOnEscape?: boolean;
     /* blazorSuppress */
     /**
-     * @deprecated The `outlet` property is deprecated and no longer has any effect.
-     * The overlay service now always renders content in place using the HTML Popover API.
-     * This property will be removed in a future version.
+     * @deprecated Still supported and used by the overlay service when provided but will
+     * be removed in a future version. Avoid using this property in new code and prefer
+     * the default in-place rendering with the HTML Popover API.
      */
     outlet?: IgxOverlayOutletDirective | ElementRef;
     /**
diff --git a/projects/igniteui-angular/date-picker/src/date-picker/date-picker.component.ts b/projects/igniteui-angular/date-picker/src/date-picker/date-picker.component.ts
@@ -244,9 +244,9 @@ export class IgxDatePickerComponent extends PickerBaseDirective implements Contr
     public spinDelta: Pick<DatePartDeltas, 'date' | 'month' | 'year'>;
 
     /**
-     * @deprecated The `outlet` property is deprecated and no longer has any effect.
-     * The overlay service now always renders content in place using the HTML Popover API.
-     * This property will be removed in a future version.
+     * @deprecated Still supported and used by the overlay service when provided but will
+     * be removed in a future version. Avoid using this property in new code and prefer
+     * the default in-place rendering with the HTML Popover API.
      *
      * Gets/Sets the container used for the popup element.
      *
diff --git a/projects/igniteui-angular/date-picker/src/date-picker/picker-base.directive.ts b/projects/igniteui-angular/date-picker/src/date-picker/picker-base.directive.ts
@@ -186,9 +186,9 @@ export abstract class PickerBaseDirective implements IToggleView, EditorProvider
     }
 
     /**
-     * @deprecated The `outlet` property is deprecated and no longer has any effect.
-     * The overlay service now always renders content in place using the HTML Popover API.
-     * This property will be removed in a future version.
+     * @deprecated Still supported and used by the overlay service when provided but will
+     * be removed in a future version. Avoid using this property in new code and prefer
+     * the default in-place rendering with the HTML Popover API.
      *
      * The container used for the pop-up element.
      *
diff --git a/projects/igniteui-angular/date-picker/src/date-range-picker/date-range-picker.component.ts b/projects/igniteui-angular/date-picker/src/date-range-picker/date-range-picker.component.ts
@@ -367,9 +367,9 @@ export class IgxDateRangePickerComponent extends PickerBaseDirective
     public override placeholder = '';
 
     /**
-     * @deprecated The `outlet` property is deprecated and no longer has any effect.
-     * The overlay service now always renders content in place using the HTML Popover API.
-     * This property will be removed in a future version.
+     * @deprecated Still supported and used by the overlay service when provided but will
+     * be removed in a future version. Avoid using this property in new code and prefer
+     * the default in-place rendering with the HTML Popover API.
      *
      * Gets/Sets the container used for the popup element.
      *
diff --git a/projects/igniteui-angular/directives/src/directives/toggle/README.md b/projects/igniteui-angular/directives/src/directives/toggle/README.md
@@ -103,11 +103,11 @@ Providing reference from custom component which has already been registered into
 |:----------:|:-------------|:------|
 | `igxToggleAction`| `IToggleView` \| `string` | Determines the target that have to be controled. |
 | `overlaySettings` | `OverlaySettings`| Passes `igxOverlay` settings for applicable targets (`igxToggle`) that control positioning, interaction and scroll behavior.
-| `igxToggleOutlet` | `IgxOverlayOutletDirective` \| `ElementRef`| **Deprecated.** No longer has any effect. The overlay service now always renders content in place using the HTML Popover API. This property will be removed in a future version.
+| `igxToggleOutlet` | `IgxOverlayOutletDirective` \| `ElementRef`| **Deprecated.** Still supported and used by the overlay service when provided but will be removed in a future version. Avoid using this property in new code and prefer the default in-place rendering with the HTML Popover API.
 
 # IgxOverlayOutlet Directive
 
-> **Deprecated.** The `IgxOverlayOutletDirective` and the `outlet` property on `OverlaySettings` are deprecated and no longer have any effect. The overlay service now always renders content in place using the HTML Popover API. These will be removed in a future version.
+> **Deprecated.** The `IgxOverlayOutletDirective` and the `outlet` property on `OverlaySettings` are deprecated. They are still supported and used by the overlay service when provided but will be removed in a future version. Avoid using this property in new code and prefer the default in-place rendering with the HTML Popover API.
 
 The **IgxOverlayOutlet** provides a way to mark an element as an `igxOverlay` outlet container through the component template only.
 Directive instance is exported as `overlay-outlet`, so it can be assigned within the template:
diff --git a/projects/igniteui-angular/directives/src/directives/toggle/toggle.directive.ts b/projects/igniteui-angular/directives/src/directives/toggle/toggle.directive.ts
@@ -445,9 +445,9 @@ export class IgxToggleActionDirective implements OnInit {
      * ```
      * Where `outlet` in an instance of `IgxOverlayOutletDirective` or an `ElementRef`
      *
-     * @deprecated The `outlet` property is deprecated and no longer has any effect.
-     * The overlay service now always renders content in place using the HTML Popover API.
-     * This property will be removed in a future version.
+     * @deprecated Still supported and used by the overlay service when provided but will
+     * be removed in a future version. Avoid using this property in new code and prefer
+     * the default in-place rendering with the HTML Popover API.
      */
     @Input('igxToggleOutlet')
     public outlet: IgxOverlayOutletDirective | ElementRef;
diff --git a/projects/igniteui-angular/drop-down/src/drop-down/autocomplete/autocomplete.directive.ts b/projects/igniteui-angular/drop-down/src/drop-down/autocomplete/autocomplete.directive.ts
@@ -33,9 +33,9 @@ export interface AutocompleteOverlaySettings {
     /** Scroll strategy to use with this settings */
     scrollStrategy?: IScrollStrategy;
     /**
-     * @deprecated The `outlet` property is deprecated and no longer has any effect.
-     * The overlay service now always renders content in place using the HTML Popover API.
-     * This property will be removed in a future version.
+     * @deprecated Still supported and used by the overlay service when provided but will
+     * be removed in a future version. Avoid using this property in new code and prefer
+     * the default in-place rendering with the HTML Popover API.
      *
      * Set the outlet container to attach the overlay to */
     outlet?: IgxOverlayOutletDirective | ElementRef;
diff --git a/projects/igniteui-angular/grids/hierarchical-grid/src/hierarchical-grid-base.directive.ts b/projects/igniteui-angular/grids/hierarchical-grid/src/hierarchical-grid-base.directive.ts
@@ -83,9 +83,9 @@ export abstract class IgxHierarchicalGridBaseDirective extends IgxGridBaseDirect
 
     /* blazorSuppress */
     /**
-     * @deprecated The `outlet` property is deprecated and no longer has any effect.
-     * The overlay service now always renders content in place using the HTML Popover API.
-     * This property will be removed in a future version.
+     * @deprecated Still supported and used by the overlay service when provided but will
+     * be removed in a future version. Avoid using this property in new code and prefer
+     * the default in-place rendering with the HTML Popover API.
      *
      * Gets the outlet used to attach the grid's overlays to.
      *
@@ -98,9 +98,9 @@ export abstract class IgxHierarchicalGridBaseDirective extends IgxGridBaseDirect
 
     /* blazorSuppress */
     /**
-     * @deprecated The `outlet` property is deprecated and no longer has any effect.
-     * The overlay service now always renders content in place using the HTML Popover API.
-     * This property will be removed in a future version.
+     * @deprecated Still supported and used by the overlay service when provided but will
+     * be removed in a future version. Avoid using this property in new code and prefer
+     * the default in-place rendering with the HTML Popover API.
      *
      * Sets the outlet used to attach the grid's overlays to.
      */

Original file line number	Diff line number	Diff line change
`@@ -244,9 +244,9 @@ export class IgxDatePickerComponent extends PickerBaseDirective implements Contr`
`244`	`244`	`public spinDelta: Pick<DatePartDeltas, 'date' \| 'month' \| 'year'>;`
`245`	`245`
`246`	`246`	`/**`
`247`		- * @deprecated The `outlet` property is deprecated and no longer has any effect.
`248`		`- * The overlay service now always renders content in place using the HTML Popover API.`
`249`		`- * This property will be removed in a future version.`
	`247`	`+ * @deprecated Still supported and used by the overlay service when provided but will`
	`248`	`+ * be removed in a future version. Avoid using this property in new code and prefer`
	`249`	`+ * the default in-place rendering with the HTML Popover API.`
`250`	`250`	`*`
`251`	`251`	`* Gets/Sets the container used for the popup element.`
`252`	`252`	`*`
Original file line number	Diff line number	Diff line change
`@@ -186,9 +186,9 @@ export abstract class PickerBaseDirective implements IToggleView, EditorProvider`
`186`	`186`	`}`
`187`	`187`
`188`	`188`	`/**`
`189`		- * @deprecated The `outlet` property is deprecated and no longer has any effect.
`190`		`- * The overlay service now always renders content in place using the HTML Popover API.`
`191`		`- * This property will be removed in a future version.`
	`189`	`+ * @deprecated Still supported and used by the overlay service when provided but will`
	`190`	`+ * be removed in a future version. Avoid using this property in new code and prefer`
	`191`	`+ * the default in-place rendering with the HTML Popover API.`
`192`	`192`	`*`
`193`	`193`	`* The container used for the pop-up element.`
`194`	`194`	`*`
Original file line number	Diff line number	Diff line change
`@@ -367,9 +367,9 @@ export class IgxDateRangePickerComponent extends PickerBaseDirective`
`367`	`367`	`public override placeholder = '';`
`368`	`368`
`369`	`369`	`/**`
`370`		- * @deprecated The `outlet` property is deprecated and no longer has any effect.
`371`		`- * The overlay service now always renders content in place using the HTML Popover API.`
`372`		`- * This property will be removed in a future version.`
	`370`	`+ * @deprecated Still supported and used by the overlay service when provided but will`
	`371`	`+ * be removed in a future version. Avoid using this property in new code and prefer`
	`372`	`+ * the default in-place rendering with the HTML Popover API.`
`373`	`373`	`*`
`374`	`374`	`* Gets/Sets the container used for the popup element.`
`375`	`375`	`*`