Open Source

Overlay Styling

IgxOverlayService is used to display content above the page content. A lot of Ignite UI for Angular components use the overlay - Drop Down, Combo, Date Picker and more - so it is important to understand how the overlay displays content. To display the content above other elements, the service moves it into a special outlet container (attached at the end of the document’s body, by default). This behavior can affect styles scoped to specific container.

Styling Overlay Components

A theme emitted from the global stylesheet can affect content in any overlay outlet. For example, the following Drop Down theme emits universal token overrides at the Sass root, where they are available to drop-down content attached to the document body:

{/* overlay-styling.component.html */}
<igx-drop-down #customDropDown height="350px">
    <igx-drop-down-item *ngFor="let item of items" [value]="item.id">
        {{ item.name }}
    </igx-drop-down-item>
</igx-drop-down>

// styles.scss
@use "igniteui-angular/theming" as *;

$my-drop-down-theme: drop-down-theme(
  $background-color: #efefef
);

@include tokens($my-drop-down-theme);

Because these universal overrides are global, the drop-down content can consume them after the overlay service moves it to an outlet.

Scoped Component Styles

A local theme can only affect overlay content that inherits from its container or matches its generated selectors. Content attached to the default outlet at the end of body is not a descendant of the component that opened it.

For example, the igx-combo item styles use the drop-down theme. This component-local theme takes effect after the combo outlet is moved beneath the host:

// overlay-styling.component.scss

:host {
  @include tokens($my-drop-down-theme);
}

::ng-deep does not make tokens inherit into a detached outlet. Either emit the overlay theme globally or move the outlet beneath the themed container. If a special customization uses scoped mode and its generated selectors still cannot match the nested overlay content, ::ng-deep may also be required after moving the outlet.

Use the OverlaySettings.outlet property to control where the overlay container is rendered.

Here, we can pass a reference to the element where we’d like our container to be:

<igx-combo [data]="items" valueKey="name" displayKey="name" [overlaySettings]="{ outlet: element, modal: true }">
</igx-combo>

export class OverlayStylingComponent {
  ...
  constructor(public element: ElementRef) {
  }
}

Now, the combo’s list of items are properly rendered inside of our component’s host, which means that our custom theme will take effect:

Styling The Overlay

Now that we’ve covered how ViewEncapsulation works along with the overlay’s outlet property, we can take a look at how we can style the overlay’s wrapper itself. The overlay-theme exposes a single property - $background-color, which affects the color of the backdrop when the overlay is set to modal: true.

Global Styles

The easiest way to style the overlay modal is to include its theme in our app’s global styles:

// styles.scss
$my-overlay-theme: overlay-theme(
  $background-color: rgba(0, 153, 255, 0.3)
);

@include tokens($my-overlay-theme);

Now all modal overlays will have a purple tint. Because this theme is emitted globally, Angular View Encapsulation and ::ng-deep are not involved.

Scoped Overlay Styles

To give an overlay a specific background only beneath a certain container, move its outlet under that container and scope the theme there. Custom outlets have some limitations; to reduce overflow clipping, stacking, and viewport issues, use them in higher-level components:

// styles.scss
...
.purple {
  @include tokens($my-overlay-theme);
}