diff --git a/docs/angular/src/content/en/.gitignore b/docs/angular/src/content/en/.gitignore index 7b9ece5436..945949e54b 100644 --- a/docs/angular/src/content/en/.gitignore +++ b/docs/angular/src/content/en/.gitignore @@ -64,6 +64,7 @@ components/pivotGrid/*.mdx /components/charts/ /components/inputs/ /components/layouts/ +/components/notifications/ /components/geo-map*.mdx /components/spreadsheet-*.mdx /components/excel-library*.mdx diff --git a/docs/angular/src/content/en/components/dialog.mdx b/docs/angular/src/content/en/components/dialog.mdx deleted file mode 100644 index b564ded9e8..0000000000 --- a/docs/angular/src/content/en/components/dialog.mdx +++ /dev/null @@ -1,370 +0,0 @@ ---- -title: Angular Dialog Window Component - MIT license -description: Whether building informative dialogs or data manipulation windows, Ignite UI for Angular Dialog Window component can manage information shown in real-time for fast capability. -keywords: Ignite UI for Angular, UI controls, Angular widgets, web widgets, UI widgets, Angular, Native Angular Components Suite, Angular UI Components, Native Angular Components Library, Angular Dialog Window component, Angular Dialog Window control, Angular Dialog Component -license: MIT -llms: - description: "Use the Ignite UI for Angular Dialog Window component to display messages or present forms for users to fill out." ---- - -import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; -import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; -import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; - -# Angular Dialog Window Component Overview - -
-Use the Ignite UI for Angular Dialog Window component to display messages or present forms for users to fill out. The component opens a dialog window centered on top of app content. You can also provide a standard alert message that users can cancel. -
- -## Angular Dialog Window Example - - - -
- -## Getting Started with Ignite UI for Angular Dialog Window - -To get started with the Ignite UI for Angular Dialog Window component, first you need to install Ignite UI for Angular. In an existing Angular application, type the following command: - -```cmd -ng add igniteui-angular -``` - -For a complete introduction to the Ignite UI for Angular, read the [_getting started_](/general/getting-started) topic. - -The next step is to import the `IgxDialogModule` in your **app.module.ts** file. - -```typescript -// app.module.ts - -... -import { IgxDialogModule } from 'igniteui-angular/dialog'; -// import { IgxDialogModule } from '@infragistics/igniteui-angular'; for licensed package - -@NgModule({ - ... - imports: [..., IgxDialogModule], - ... -}) -export class AppModule {} -``` - -Alternatively, as of `16.0.0` you can import the `IgxDialogComponent` as a standalone dependency, or use the [`IGX_DIALOG_DIRECTIVES`](https://github.com/IgniteUI/igniteui-angular/blob/master/projects/igniteui-angular/dialog/src/dialog/public_api.ts) token to import the component and all of its supporting components and directives. - -```typescript -// home.component.ts - -import { IGX_DIALOG_DIRECTIVES } from 'igniteui-angular/dialog'; -import { IgxButtonDirective } from 'igniteui-angular/directives'; -import { IgxRippleDirective } from 'igniteui-angular/directives'; -// import { IGX_DIALOG_DIRECTIVES, IgxButtonDirective, IgxRippleDirective } from '@infragistics/igniteui-angular'; for licensed package - -@Component({ - selector: 'app-home', - template: ` - - - - - `, - styleUrls: ['home.component.scss'], - standalone: true, - imports: [IGX_DIALOG_DIRECTIVES, IgxButtonDirective, IgxRippleDirective] - /* or imports: [IgxDialogComponent, IgxButtonDirective, IgxRippleDirective] */ -}) -export class HomeComponent {} -``` - - -This component uses Material Icons. Add the following link to your `index.html`: `` - - -Now that you have the Ignite UI for Angular Dialog Window module or directives imported, you can start using the `igx-dialog` component. - -
- -## Using the Angular Dialog Window - -### Alert Dialog - -To create an alert dialog, in the template of our email component, we add the following code. We have to set the , , - and handle event: - -```html -{/*email.component.html*/} - - - - -``` - -If everything's done right, you should see the demo sample shown above in your browser. - -
- -### Standard Dialog - -To create a standard dialog, in the template of our file manager component, we add the following code. We have to set the , , -, , and handle and events: - -```html -{/*file-manager.component.html*/} - - - - -``` - - - -
- -### Custom Dialog - -To create a custom dialog, in the template of our sign-in component, we add the following code. The dialog title area can be customized using the `igxDialogTitle` directive or the `igx-dialog-title` selector. The actions area can be customized using the `igxDialogActions` directive or the `igx-dialog-actions` selector. -We add two input groups consisting of a label and and input decorated with the [**igxLabel**](/input-group) and [**igxInput**](/input-group) directives. - -```html -{/*sign-in.component.html*/} - - - - -
- - vpn_key -
-Sign In -
- -
- - -
- - - person - - - - - - - lock - - - - -
- -
- - - -
- -``` - - - -
- -### Position and Animation Settings - -There are two ways to change the position at which the `igx-dialog` will be shown: - -- Using method and pass a valid . Example: - -```typescript -import { PositionSettings, OverlaySettings, GlobalPositionStrategy, NoOpScrollStrategy, HorizontalAlignment, VerticalAlignment } from 'igniteui-angular/core'; -// import { PositionSettings, OverlaySettings, GlobalPositionStrategy, NoOpScrollStrategy, HorizontalAlignment, VerticalAlignment } from '@infragistics/igniteui-angular'; for licensed package - -@Component({...}) -export class HomeComponent { - public positionSettingsOnOpen: PositionSettings = { - horizontalDirection: HorizontalAlignment.Right, - verticalDirection: VerticalAlignment.Middle, - horizontalStartPoint: HorizontalAlignment.Right, - verticalStartPoint: VerticalAlignment.Middle, - }; - public overlaySettings: OverlaySettings = { - positionStrategy: new GlobalPositionStrategy(this.positionSettingsOnOpen), - scrollStrategy: new NoOpScrollStrategy(), - modal: false, - closeOnOutsideClick: true - }; - - public openDialog() { - this.alert.open(this.overlaySettings); - } -} -``` - -- Using the `@Input`. Example: - -```html - - -``` - -```typescript -import { useAnimation } from '@angular/animations'; -import { slideInTop, slideOutBottom } from 'igniteui-angular/animations'; -import { PositionSettings, HorizontalAlignment, VerticalAlignment } from 'igniteui-angular/core'; -// import { PositionSettings, HorizontalAlignment, VerticalAlignment } from '@infragistics/igniteui-angular'; for licensed package - -@Component({...}) -export class HomeComponent { - public positionSettings: PositionSettings = { - openAnimation: useAnimation(slideInTop, { params: { duration: '2000ms' } }), - closeAnimation: useAnimation(slideOutBottom, { params: { duration: '2000ms'} }), - horizontalDirection: HorizontalAlignment.Left, - verticalDirection: VerticalAlignment.Middle, - horizontalStartPoint: HorizontalAlignment.Left, - verticalStartPoint: VerticalAlignment.Middle, - minSize: { height: 100, width: 100 } - }; -} -``` - - -The same approach should be used for the animation settings, use the `openAnimation` and `closeAnimation` properties to define animation params like duration. - -`params` object example: - -```typescript -params: { - delay: '0s', - duration: '350ms', - easing: EaseOut.quad, - endOpacity: 1, - fromPosition: 'translateX(-500px)', - startOpacity: 0, - toPosition: 'translateY(0)' -} -``` - -### Trap focus inside dialog - -By default when the dialog is opened the Tab key focus is trapped within it, i.e. the focus does not leave the element when the user keeps tabbing through the focusable elements. When the focus leaves the last element, it moves to the first one and vice versa, when SHIFT + TAB is pressed, when the focus leaves the first element, the last element should be focused. In case the dialog does not contain any focusable elements, the focus will be trapped on the dialog container itself. This behavior can be changed by setting the property. - -## Styling - -### Dialog Theme Property Map - -Changing the `$background` property automatically updates the following dependent properties: - -| Primary Property | Dependent Property | Description | -| --- | --- | --- | -| **$background** | $title-color | The dialog title text color. | -| | $message-color | The dialog message text color. | -| | $border-color | The border color used for dialog component. | - -To get started with styling the dialog window, we need to import the `index` file, where all the theme functions and the `tokens()` mixin are exported: - -```scss -@use "igniteui-angular/theming" as *; - -// IMPORTANT: Prior to Ignite UI for Angular version 13 use: -// @import '~igniteui-angular/lib/core/styles/themes/index'; -``` - -Following the simplest approach, we create a new theme that extends the and accepts parameters that style the dialog. By providing the `$background`, the theme automatically selects suitable contrast colors for the foreground properties. However, you can still manually define them if desired. - -```scss -$my-dialog-theme: dialog-theme( - $background: #011627, - $title-color: #ecaa53, - $border-radius: 5px, -); -``` - - -In order to style any additional components that are used as part of the dialog window's content (such as the [`IgxButton`](./inputs/button.mdx)), an additional theme should be created that is specific to the respective component and is placed under the dialog window's scope only (so it does not affect the rest of the application). - - -```scss -$custom-button: contained-button-theme( - $background: #ecaa53, - $foreground: #011627, -); -``` - -Since the dialog window uses the [`IgxOverlayService`](/overlay), in order for our custom theme to reach down the dialog window that we want to style, we will provide a specific outlet where the dialog window will be placed in the DOM when it is visible. - -```html -
- - {/* .... */} - -
-``` - - -In order to learn more about the various options for providing themes to elements that are shown by using the [`IgxOverlayService`](/overlay), you can take a look at the [Overlay styling topic](/overlay-styling). - - -### Including Themes - - - -The last step is to **include** the component theme in our application. - -```scss -:host { - @include tokens($my-dialog-theme); -} -``` - - -In some component templates, Emulated View Encapsulation can still prevent the generated token declarations from reaching nested Ignite UI elements. If the theme does not take effect, use `::ng-deep` as shown below or move the theme to a global stylesheet. - - -```scss -:host { - ::ng-deep { - @include tokens($my-dialog-theme); - } -} -``` - -### Demo - - - -
- -## API References -
-- -- -- -- -## Theming Dependencies - -- -- -- - -## Additional Resources - -
- -Our community is active and always welcoming to new ideas. - -- [Ignite UI for Angular **Forums**](https://www.infragistics.com/community/forums/f/ignite-ui-for-angular) -- [Ignite UI for Angular **GitHub**](https://github.com/IgniteUI/igniteui-angular) diff --git a/docs/angular/src/content/en/components/general/cli/component-templates.mdx b/docs/angular/src/content/en/components/general/cli/component-templates.mdx index f36297e414..c896738acb 100644 --- a/docs/angular/src/content/en/components/general/cli/component-templates.mdx +++ b/docs/angular/src/content/en/components/general/cli/component-templates.mdx @@ -87,7 +87,7 @@ These templates generate components into an existing Angular workspace only. The | chat | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c chat newChat
Ignite UI CLI:
ig add chat newChat
Basic IgxChat sample.
| [Chat](../../chat.mdx) component for conversational interfaces. | | ripple | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c ripple newRipple
Ignite UI CLI:
ig add ripple newRipple
Basic IgxRipple sample.
| [IgxRipple](../../ripple.mdx) directive adding a ripple animation on interaction. | | slider | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c slider newSlider
Ignite UI CLI:
ig add slider newSlider
Basic IgxSlider sample.
| [IgxSlider](../../slider/slider.mdx) for selecting a value by moving a thumb along a track. | -| dialog | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c dialog newDialog
Ignite UI CLI:
ig add dialog newDialog
Basic IgxDialog.
| Sample of the [IgxDialog](../../dialog.mdx) used as a standard confirmation dialog. | +| dialog | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c dialog newDialog
Ignite UI CLI:
ig add dialog newDialog
Basic IgxDialog.
| Sample of the [IgxDialog](../../notifications/dialog.mdx) used as a standard confirmation dialog. | | tooltip | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c tooltip newTooltip
Ignite UI CLI:
ig add tooltip newTooltip
A fully customizable tooltip.
| Basic tooltip created with the [IgxTooltip](../../tooltip.mdx). | | Scheduling | | | | date-picker | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c date-picker newDatePicker
Ignite UI CLI:
ig add date-picker newDatePicker
Basic IgxDatePicker.
| Basic [IgxDatePicker](../../date-picker.mdx) with one-way data binding. | diff --git a/docs/angular/src/content/en/components/themes/misc/angular-material-theming.mdx b/docs/angular/src/content/en/components/themes/misc/angular-material-theming.mdx index 635846ddd6..e7dda06975 100644 --- a/docs/angular/src/content/en/components/themes/misc/angular-material-theming.mdx +++ b/docs/angular/src/content/en/components/themes/misc/angular-material-theming.mdx @@ -416,7 +416,7 @@ Related topics: - [Typography](../sass/typography.mdx) - [Avatar Component](../../layouts/avatar.mdx) - [Button Component](inputs/button) -- [Dialog Component](../../dialog.mdx) +- [Dialog Component](../../notifications/dialog.mdx) - [Icon Component](../../layouts/icon.mdx) - [Expansion Panel Component](../../expansion-panel.mdx) ## Additional Resources diff --git a/docs/angular/src/content/en/components/themes/misc/bootstrap-theming.mdx b/docs/angular/src/content/en/components/themes/misc/bootstrap-theming.mdx index 12ba858b43..450ffd7011 100644 --- a/docs/angular/src/content/en/components/themes/misc/bootstrap-theming.mdx +++ b/docs/angular/src/content/en/components/themes/misc/bootstrap-theming.mdx @@ -369,7 +369,7 @@ Ignite UI for Angular exposes four default type scales for each of its themes, w - [Typography](/themes/sass/typography) - [Avatar Component](../../layouts/avatar.mdx) - [Button Component](inputs/button) -- [Dialog Component](/dialog) +- [Dialog Component](../../notifications/dialog.mdx) - [Icon Component](/layouts/icon) - [List Component](/list) diff --git a/docs/angular/src/content/en/components/toc.json b/docs/angular/src/content/en/components/toc.json index 556134dbb6..29a1ed4603 100644 --- a/docs/angular/src/content/en/components/toc.json +++ b/docs/angular/src/content/en/components/toc.json @@ -2127,7 +2127,8 @@ }, { "name": "Dialog Window", - "href": "dialog.mdx" + "href": "notifications/dialog.mdx", + "updated": true }, { "name": "Slider", diff --git a/docs/angular/src/content/en/images/anatomy-content-light/dialog-lt-a.png b/docs/angular/src/content/en/images/anatomy-content-light/dialog-lt-a.png new file mode 100644 index 0000000000..a3498eba36 Binary files /dev/null and b/docs/angular/src/content/en/images/anatomy-content-light/dialog-lt-a.png differ diff --git a/docs/angular/src/content/en/images/dialog/dialog-do-1.png b/docs/angular/src/content/en/images/dialog/dialog-do-1.png new file mode 100644 index 0000000000..6c26e6f49c Binary files /dev/null and b/docs/angular/src/content/en/images/dialog/dialog-do-1.png differ diff --git a/docs/angular/src/content/en/images/dialog/dialog-do-2.png b/docs/angular/src/content/en/images/dialog/dialog-do-2.png new file mode 100644 index 0000000000..424cf3e294 Binary files /dev/null and b/docs/angular/src/content/en/images/dialog/dialog-do-2.png differ diff --git a/docs/angular/src/content/en/images/dialog/dialog-do-not-1.png b/docs/angular/src/content/en/images/dialog/dialog-do-not-1.png new file mode 100644 index 0000000000..9700dfa96a Binary files /dev/null and b/docs/angular/src/content/en/images/dialog/dialog-do-not-1.png differ diff --git a/docs/angular/src/content/en/images/dialog/dialog-do-not-2.png b/docs/angular/src/content/en/images/dialog/dialog-do-not-2.png new file mode 100644 index 0000000000..cf17d06e73 Binary files /dev/null and b/docs/angular/src/content/en/images/dialog/dialog-do-not-2.png differ diff --git a/docs/xplat/src/assets/images/dialog/dialog-do-1.png b/docs/xplat/src/assets/images/dialog/dialog-do-1.png new file mode 100644 index 0000000000..6c26e6f49c Binary files /dev/null and b/docs/xplat/src/assets/images/dialog/dialog-do-1.png differ diff --git a/docs/xplat/src/assets/images/dialog/dialog-do-2.png b/docs/xplat/src/assets/images/dialog/dialog-do-2.png new file mode 100644 index 0000000000..424cf3e294 Binary files /dev/null and b/docs/xplat/src/assets/images/dialog/dialog-do-2.png differ diff --git a/docs/xplat/src/assets/images/dialog/dialog-do-not-1.png b/docs/xplat/src/assets/images/dialog/dialog-do-not-1.png new file mode 100644 index 0000000000..9700dfa96a Binary files /dev/null and b/docs/xplat/src/assets/images/dialog/dialog-do-not-1.png differ diff --git a/docs/xplat/src/assets/images/dialog/dialog-do-not-2.png b/docs/xplat/src/assets/images/dialog/dialog-do-not-2.png new file mode 100644 index 0000000000..cf17d06e73 Binary files /dev/null and b/docs/xplat/src/assets/images/dialog/dialog-do-not-2.png differ diff --git a/docs/xplat/src/content/en/components/interactivity/accessibility-compliance.mdx b/docs/xplat/src/content/en/components/interactivity/accessibility-compliance.mdx index d22346fba5..d9b72414b0 100644 --- a/docs/xplat/src/content/en/components/interactivity/accessibility-compliance.mdx +++ b/docs/xplat/src/content/en/components/interactivity/accessibility-compliance.mdx @@ -98,7 +98,7 @@ This index records what each component's documentation covers today. **Not docum | [Combo](../combo.mdx#keyboard-navigation) | Documented | Not documented yet | [Keyboard navigation](../combo.mdx#keyboard-navigation) | | [Date Time Editor](../date-time-editor.mdx#keyboard-navigation) | Documented | Not documented yet | [Keyboard navigation](../date-time-editor.mdx#keyboard-navigation) | | [Date Picker](../date-picker.mdx#keyboard-navigation) | Documented | Not documented yet | [Keyboard navigation](../date-picker.mdx#keyboard-navigation) | -| [Dialog](../dialog.mdx) | Not documented yet | Not documented yet | — | +| [Dialog](../notifications/dialog.mdx#accessibility) | Documented | Documented | [Accessibility](../notifications/dialog.mdx#accessibility) | | [Divider](../divider.mdx) | Not documented yet | Not documented yet | — | | [Drop Down](../drop-down.mdx) | Not documented yet | Not documented yet | — | | [Expansion Panel](../expansion-panel.mdx) | Not documented yet | Not documented yet | — | @@ -146,7 +146,7 @@ This index records what each component's documentation covers today. **Not docum | [Combo](../inputs/combo/overview.mdx#keyboard-navigation) | Documented | Not documented yet | [Keyboard navigation](../inputs/combo/overview.mdx#keyboard-navigation) | | [Date Time Input](../inputs/date-time-input.mdx#keyboard-navigation) | Documented | Not documented yet | [Keyboard navigation](../inputs/date-time-input.mdx#keyboard-navigation) | | [Date Picker](../scheduling/date-picker.mdx#keyboard-navigation) | Documented | Not documented yet | [Keyboard navigation](../scheduling/date-picker.mdx#keyboard-navigation) | -| [Dialog](../notifications/dialog.mdx) | Not documented yet | Not documented yet | — | +| [Dialog](../notifications/dialog.mdx#accessibility) | Documented | Documented | [Accessibility](../notifications/dialog.mdx#accessibility) | | [Divider](../layouts/divider.mdx) | Not documented yet | Not documented yet | — | | [Dock Manager](../layouts/dock-manager.mdx#keyboard-navigation) | Documented | Not documented yet | [Keyboard navigation](../layouts/dock-manager.mdx#keyboard-navigation) | | [Dropdown](../inputs/dropdown.mdx) | Not documented yet | Not documented yet | — | diff --git a/docs/xplat/src/content/en/components/notifications/dialog.mdx b/docs/xplat/src/content/en/components/notifications/dialog.mdx index bc360e88af..a4577d03f5 100644 --- a/docs/xplat/src/content/en/components/notifications/dialog.mdx +++ b/docs/xplat/src/content/en/components/notifications/dialog.mdx @@ -1,83 +1,163 @@ --- -title: "{Platform} Dialog | Infragistics" -description: With {ProductName} Dialog component, developers can easily integrate a dialog window centered on top of app content. -keywords: "{ProductName}, UI controls, {Platform} widgets, web widgets, UI widgets, {Platform}, Native {Platform} Components Suite, Native {Platform} Controls, Native {Platform} Components Library, {Platform} Dialog components" +title: "{Platform} Dialog Component" +description: "The {ProductName} Dialog shows a message, a confirmation, or a form in a modal window that users complete or close before they continue." +keywords: "{Platform} Dialog, {ProductName}, modal dialog, alert dialog, confirmation dialog, dialog form" license: MIT +last_updated: "2026-10-15" +relatedComponents: ["Banner", "Snackbar", "Toast"] mentionedTypes: ["Dialog"] llms: - description: "The {ProductName} Dialog component is used to display some information or prompt the user for an action or confirmation." + description: "The {ProductName} Dialog is a component that shows a message, a confirmation, or a form in a modal window that users complete or close before they continue." --- import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; +import Anatomy from 'igniteui-astro-components/components/mdx/Anatomy.astro'; +import DoDont from 'igniteui-astro-components/components/mdx/DoDont.astro'; +import Faq from 'igniteui-astro-components/components/mdx/Faq.astro'; +import FaqItem from 'igniteui-astro-components/components/mdx/FaqItem.astro'; +import dialogAnatomy from '@xplat-images/anatomy-content-light/dialog-lt-a.png'; +import dialogDoLabels from '@xplat-images/dialog/dialog-do-1.png'; +import dialogDoNotLabels from '@xplat-images/dialog/dialog-do-not-1.png'; +import dialogDoActions from '@xplat-images/dialog/dialog-do-2.png'; +import dialogDoNotActions from '@xplat-images/dialog/dialog-do-not-2.png'; +# Dialog -# {Platform} Dialog Overview +The {ProductName} Dialog is a component that shows a message, a confirmation, or a form in a modal window that users complete or close before they continue. -The {ProductName} Dialog component is used to display some information or prompt the user for an action or confirmation. It is shown in a modal window, which means that the user is not allowed to interact with the main app until a certain action is performed that closes the dialog. + -## {ProductName} Dialog Example +The Angular Dialog is the `igx-dialog` component. It shows a title, a message, and up to two built-in buttons, or the title, content, and actions that you project into it. -This sample demonstrates how to create a Dialog component in {Platform}. + - + +The Dialog is built on the native `dialog` element. It shows a title, a message, your content, and the action buttons in its footer, and it closes when the user presses Escape. + +## Live Demo -### Usage + + - + + -First, you need to install the {ProductName} by running the following command: + -```cmd -npm install {PackageWebComponents} + + +## Anatomy + +The main elements include a title, a body, and action buttons. + + + + + +1. Title: should be brief and clearly describe the dialog’s task or purpose
+2. Body: contains the information and/or controls needed to complete the dialog’s task. It can include message text and components
+3. Action Buttons: the main actions needed to complete or cancel the dialog task + + + +The `igc-dialog` element renders a backdrop and a native `dialog` element with a header, a content section, and a footer: + +```text +igc-dialog +└─ #shadow-root + ├─ div[part="backdrop"] // the backdrop behind the open dialog + └─ dialog[part="base"][role="dialog"] // opened as a modal dialog + ├─ header[part="title"] // hidden when the dialog has no title + │ └─ slot[name="title"] // falls back to the title property + ├─ section[part="content"] + │ ├─ slot[name="message"] // hidden when empty + │ └─ slot // the content of the dialog + └─ footer[part="footer"] + └─ slot[name="footer"] // falls back to the default OK button +``` + + + + + +While the Angular Dialog is open, the overlay renders it inside the `igx-dialog` element, in the top layer of the page: + +```text +igx-dialog +└─ div.igx-overlay__wrapper--modal[popover="manual"] // the backdrop of a modal dialog + └─ div.igx-overlay__content--modal + └─ div.igx-dialog[tabindex="0"] // keeps the focus inside the dialog + └─ div.igx-dialog__window[role] + ├─ div.igx-dialog__window-title // the title, or the projected igx-dialog-title + ├─ div.igx-dialog__window-content + │ └─ span.igx-dialog__window-message // the message, or the projected content + └─ div.igx-dialog__window-actions // the built-in buttons, or the projected igx-dialog-actions ``` +## Getting Started + +To use the {Platform} Dialog, follow the [{ProductName} Getting Started](../general/getting-started.mdx)[{ProductName} Getting Started](../general-getting-started.mdx) topic for the basic project setup, then add the component for your target platform. +Install the **{PackageCommon}** package: + +```cmd +npm install {PackageCommon} +``` + +Then import the , its theme CSS, and register the component. The registration also registers the `igc-button` element of the default OK button: + ```ts import { defineComponents, IgcDialogComponent } from 'igniteui-webcomponents'; +import 'igniteui-webcomponents/themes/light/bootstrap.css'; defineComponents(IgcDialogComponent); ``` - - - -First, you need to the install the corresponding {ProductName} npm package by running the following command: +Install the **{PackageCommon}** package: ```cmd -npm install igniteui-react +npm install {PackageCommon} ``` -You will then need to import the {Platform} and its necessary CSS, like so: +Then import the wrapper, the `IgrButton` wrapper for the action buttons, and the theme CSS: ```tsx -import { IgrDialog } from 'igniteui-react'; +import { IgrButton, IgrDialog } from 'igniteui-react'; import 'igniteui-webcomponents/themes/light/bootstrap.css'; ``` - - -For a complete introduction to the {ProductName}, read the [**Getting Started**](../general-getting-started.mdx) topic. - - - Register the {ProductName} services: ```csharp @@ -88,49 +168,159 @@ builder.Services.AddIgniteUIBlazor(); Registering , the client resource module of the , is **optional**: the component loads its resources when it first renders. Listing it in `builder.Services.AddIgniteUIBlazor(typeof(IgbDialogModule))` can be used to preload resources or to support elements created only on the client (see [Component Modules](../general-getting-started.mdx#component-modules)). +Then link the theme CSS file in the app's host page (**wwwroot/index.html** in a standalone Blazor WebAssembly or Blazor Hybrid app, **Pages/_Host.cshtml** in a Blazor Server app, **Components/App.razor** in a Blazor Web App): + +```razor + +``` + + -The simplest way to display the dialog component is to use its method and call it on a button click. +If your project doesn't use {ProductName} yet, run `ng add igniteui-angular`. Then import the `IGX_DIALOG_DIRECTIVES` token and add it to the `imports` of your component. The token holds the and the `igx-dialog-title` and `igx-dialog-actions` directives. The built-in buttons of the dialog don't need extra imports, and the example below imports the `IgxButtonDirective` for the button that opens the dialog: + +```ts +import { Component } from '@angular/core'; +import { IGX_DIALOG_DIRECTIVES } from 'igniteui-angular/dialog'; +import { IgxButtonDirective } from 'igniteui-angular/directives'; +// import { IGX_DIALOG_DIRECTIVES } from '@infragistics/igniteui-angular/dialog'; for licensed package + +@Component({ + selector: 'app-home', + template: ` + + + + + `, + imports: [IGX_DIALOG_DIRECTIVES, IgxButtonDirective] +}) +export class HomeComponent {} +``` + +The built-in buttons don't close the Angular Dialog by themselves. Call `close()` in the handlers of their `leftButtonSelect` and `rightButtonSelect` events. + + + + + +After registration, render the with a title, the content, and the action buttons in the `footer` slot, and open it with the `show` method: + + + + + +```html +Delete file + + +

Are you sure you want to delete this file?

+ Cancel + Delete + +``` + +```ts +const dialog = document.getElementById('delete-dialog') as IgcDialogComponent; + +document.getElementById('open-button')!.addEventListener('click', () => dialog.show()); +document.getElementById('cancel-button')!.addEventListener('click', () => dialog.hide()); +document.getElementById('delete-button')!.addEventListener('click', () => dialog.hide()); +``` + + + + + +```tsx +import { useRef } from 'react'; +import { IgrButton, IgrDialog } from 'igniteui-react'; + +export default function DeleteFile() { + const dialogRef = useRef(null); + + return ( + <> + dialogRef.current?.show()}>Delete file + +

Are you sure you want to delete this file?

+ dialogRef.current?.hide()}>Cancel + dialogRef.current?.hide()}>Delete + + + ); +} +``` + + ```razor -
- Show Dialog - -

Are you sure you want to delete the Annual_Report_2016.pdf and Annual_Report_2017.pdf files?

- Cancel - OK - -
+Delete file + + +

Are you sure you want to delete this file?

+ Cancel + Delete + @code { - public IgbDialog DialogRef; - public async Task OnDialogShow() + private IgbDialog Dialog { get; set; } + + private async Task ShowDialog() { - if (this.DialogRef != null) - await this.DialogRef.ShowAsync(); + await Dialog.ShowAsync(); } - public async Task OnDialogHide() + + private async Task HideDialog() { - if (this.DialogRef != null) - await this.DialogRef.HideAsync(); + await Dialog.HideAsync(); } } ``` +## Usage + +Use the {Platform} Dialog to show a message or alert to the user, allowing him to take action accordingly or to present a form that requires immediate action before proceeding, such as a login. The Dialog is displayed modally, meaning that the user has to complete or close it before moving on. + +### Types + +The Dialog can be used to show an alert with only a confirming button, a message with cancellation and confirmation, or as a container for action that needs immediate attention, such as a user logging into his account. Its Button area is templatable, allowing you, for example, to adjust the buttons. + + + +For an alert, leave the `footer` slot empty, and the {Platform} Dialog shows its default OK button, which closes the dialog. For a confirmation, place the cancel and the confirm buttons in the `footer` slot. For a custom dialog, place the controls in the content of the dialog: + + + ```html -Show Dialog + +

Your email has been sent successfully!

+ + + +

Your email will be permanently deleted.

+ Cancel + OK + - -

Are you sure you want to delete the Annual_Report_2016.pdf and Annual_Report_2017.pdf files?

- Cancel - OK + + + + Cancel + Sign In ``` @@ -139,92 +329,1178 @@ The simplest way to display the dialog component is to use its ```tsx - - Show Dialog - + +

Your email has been sent successfully!

+ - - Dialog Message + +

Your email will be permanently deleted.

+ Cancel + OK -public onDialogRef(dialog: IgrDialog) { - if (!dialog) { return; } - this.dialogRef = dialog; -} + + + + Cancel + Sign In + +``` -public onDialogShow() { - if (this.dialogRef) { - this.dialogRef.show(); - } -} + + + + +```razor + +

Your email has been sent successfully!

+ + + +

Your email will be permanently deleted.

+ Cancel + OK + + + + + + Cancel + Sign In + ``` -The component provides an property, which gives you the ability to configure its state as per your application scenario. + -Use the property to set the title of the dialog. However, if any content is provided in the `title` slot, it will take precedence over the property. +For an alert, set only the `leftButtonLabel`. For a confirmation, set both the `leftButtonLabel` and the `rightButtonLabel`. For a custom dialog, project the title, the controls, and the buttons into the dialog with the `igx-dialog-title` and `igx-dialog-actions` directives: -Action buttons or additional information can be placed in the bottom part of the dialog via the `footer` slot. If no content is added there, a default `OK` button will be shown that closes the Dialog when clicked. In case you do not want this button to be shown you can set the property to **true**. The default value is **false**. +```html + + + + + + + + Sign In + + + + + + + + + + + + + +``` -### Closing + -By default, the Dialog is closed automatically when the user presses `ESC`. You could prevent this behavior using the property. The default value is **false**. If there is an open dropdown (or any other element that should handle `ESC` internally) in the dialog, pressing `ESC` once will close the dropdown and pressing it again will close the dialog. + -Use the property to configure if the dialog should be closed when clicking outside of it. The default value is **false**. + + - + + + - +### Title and Content + +The property sets the text of the dialog header. To show other content in the header, such as an icon, place it in the `title` slot, which takes precedence over the property. Place a short message in the `message` slot, which the {Platform} Dialog shows above the rest of the content and limits to a width of 40 characters. Everything else that you place in the dialog becomes its content: + + +```html + + Delete File + Are you sure you want to delete this file? +

Annual_Report_2026.pdf will be removed from all your devices.

+ +``` -### Form + -Form elements can close a Dialog if they have the attribute `method="dialog"`. Submitting the form will trigger the closing of the dialog. + - +```tsx + + Delete File + Are you sure you want to delete this file? +

Annual_Report_2026.pdf will be removed from all your devices.

+ +``` + + -## Styling +```razor + + Delete File + Are you sure you want to delete this file? +

Annual_Report_2026.pdf will be removed from all your devices.

+ +``` -The component exposes several CSS parts to give you full control over its style: + -|Name|Description| -|--|--| -| `base` | The base wrapper of the dialog. | -| `title` | The title container. | -| `footer` | The footer container. | -| `content` | The content container. | + -```css -igc-dialog::part(content) { - background: var(--ig-secondary-800); - color: var(--ig-secondary-800-contrast); -} +The and properties set the text of the dialog header and the dialog body. To show other content in the header, such as an icon, project an `igx-dialog-title` element or an element with the `igxDialogTitle` directive. Everything else that you place in the dialog becomes its content. The Angular Dialog ignores the projected title when you set `title`, and the projected content when you set `message`: -igc-dialog::part(title), -igc-dialog::part(footer) { - background: var(--ig-secondary-800); - color: var(--ig-warn-500); -} +```html + + + delete + Delete File + +

Are you sure you want to delete Annual_Report_2026.pdf?

+ + + + + ``` - + +### Action Buttons + +Place the action buttons of the {Platform} Dialog in the `footer` slot. When the slot is empty, the dialog shows a default OK button, which closes the dialog and emits the closing events. Set to hide the default button, for example when the content of the dialog has its own buttons. The property has no effect when the `footer` slot has content: -## API References - -## Additional Resources + -- [{ProductName} **Forums**]({ForumsLink}) -- [{ProductName} **GitHub**]({GithubLink}) + + +```html + +

Exporting the report. This can take a few seconds.

+ +``` + + + + + +```tsx + +

Exporting the report. This can take a few seconds.

+ +``` + + + + + +```razor + +

Exporting the report. This can take a few seconds.

+ +``` + + + + + +The and properties add the built-in buttons, and each button renders only when its label is set. The `leftButtonType` and `rightButtonType` properties set the button variant, `flat` by default, and the `leftButtonRipple` and `rightButtonRipple` properties set the ripple color. A click on a built-in button emits or , and the dialog stays open until you call `close()`: + +```html + + +``` + +For other buttons, project them into the dialog with an `igx-dialog-actions` element or an element with the `igxDialogActions` directive. The Angular Dialog ignores the projected actions when you set a button label. + + + +### Opening and Closing + + + +Open and close the {Platform} Dialog with the following methods, which play the open and the close animations: + + + + + +- opens the dialog. +- closes the dialog. +- opens the dialog when it's closed and closes it when it's open. + +Each method returns a promise that resolves to `false` when the dialog is already in the requested state. The property also opens and closes the dialog, but without the animations. + + + + + +- opens the dialog. +- closes the dialog. +- opens the dialog when it's closed and closes it when it's open. + +Each method returns `false` when the dialog is already in the requested state. The parameter also opens and closes the dialog, but without the animations, and it doesn't change when the user closes the dialog. Use the methods to keep the state in sync. + + + + + +These methods and the `open` property don't emit the closing events. To open or close the dialog without code, add the `command` and `commandfor` attributes to a button, in browsers that support the [Invoker Commands API](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API). Set `command` to `--show`, `--hide`, or `--toggle`, and set `commandfor` to the `id` of the dialog: + + + + + +```html +Delete file + + +

Are you sure you want to delete this file?

+ Cancel + +``` + + + + + +```tsx +Delete file + + +

Are you sure you want to delete this file?

+ Cancel + +``` + + + + + +```razor +Delete file + + +

Are you sure you want to delete this file?

+ Cancel + +``` + + + + + +Open and close the Angular Dialog with the following methods, which play the open and the close animations: + +- opens the dialog. It accepts optional overlay settings, as described in [Position and Animation](#position-and-animation). +- closes the dialog. +- opens the dialog when it's closed and closes it when it's open. + +To control the dialog from a property of your component, bind two-way. The property changes to `false` when the user closes the dialog: + +```html + + + + +``` + +The Angular Dialog emits and before it opens and closes, and and after the animation ends. These events also fire when you open and close the dialog in code. Set `cancel` to `true` in the handler of `opening` or `closing` to keep the dialog in its current state. + + + +### Closing on Escape and Outside Click + + + +The {Platform} Dialog closes when the user presses Escape. Set to keep it open, for example while it guards unsaved work. Set to close the dialog when the user clicks the backdrop: + + + + + +```html + + ... + + + + ... + +``` + + + + + +```tsx + + ... + + + + ... + +``` + + + + + +```razor + + ... + + + + ... + +``` + + + + + +When the user closes the dialog with Escape, a click on the backdrop, the default OK button, or a submitted form, the {Platform} Dialog emits the closing event before it closes and the closed event after the close animation ends. Cancel the closing event to keep the dialog open: + + + + + +```ts +const dialog = document.querySelector('igc-dialog')!; + +dialog.addEventListener('igcClosing', (event) => { + if (event.target === dialog && hasUnsavedChanges) { + event.preventDefault(); + } +}); +``` + + + + + +```tsx +) => { + if (event.target === event.currentTarget && hasUnsavedChanges) { + event.preventDefault(); + } + }}> + ... + +``` + + + + + +The callback can't cancel the closing, because it runs after the browser handles the event. To cancel it, set to the name of a JavaScript function that you register with `igRegisterScript`: + +```razor + + ... + +``` + +```javascript +// In JavaScript +function onDialogClosing(event) { + if (event.target === event.currentTarget && window.hasUnsavedChanges) { + event.preventDefault(); + } +} + +igRegisterScript("onDialogClosing", onDialogClosing, false); +``` + + + + + +Components in the dialog that open and close, such as the Select, emit their own `igcClosing` and `igcClosed` events, which bubble to the dialog. Check that the target of the event is the dialog before you handle it, as the examples above do. + + + + + +The Angular Dialog closes when the user presses Escape. Set to `false` to keep it open, for example while it guards unsaved work. Set to `true` to close the dialog when the user clicks outside it. The dialog reads these properties when it opens, so a change while the dialog is open takes effect the next time it opens: + +```html + + ... + + + + ... + +``` + +To keep the dialog open in other cases, cancel the `closing` event. Its `event` argument holds the keyboard or the pointer event that closes the dialog, and it's `undefined` when you call `close()`: + +```html + + ... + +``` + +```ts +import { IDialogCancellableEventArgs } from 'igniteui-angular/dialog'; + +public hasUnsavedChanges = false; + +public onClosing(args: IDialogCancellableEventArgs) { + if (args.event && this.hasUnsavedChanges) { + args.cancel = true; + } +} +``` + + + +### Forms + + + +Place a `form` element with `method="dialog"` in the content of the {Platform} Dialog to close the dialog when the user submits the form. The dialog emits the closing events, so you can cancel the closing, and it doesn't send the form to a server. To keep the submit button in the footer, as the design guidance recommends, associate it with the form: + + + + + +```html + +
+ + +
+ Cancel + Sign In + +``` + + + + + +The `form` property of the `IgrButton` is read-only, so submit the form from the click handler of the button: + +```tsx +const dialogRef = useRef(null); +const formRef = useRef(null); + + +
+ + + + dialogRef.current?.hide()}>Cancel + formRef.current?.requestSubmit()}>Sign In +
 +``` + + + + + +```razor + +
+ + + + Cancel + Sign In +
 +``` + + + + + +When a native `button` or `input` element submits the form, the {Platform} Dialog sets its to the `value` of that element. Read `returnValue` in the handler of the closed event to find out which button closed the dialog. + + + + + +The Angular Dialog doesn't close when a form in it is submitted. Handle the `submit` event of the form and call `close()`: + +```html + +
+ + + + + + + + +
+ + + + + +``` + +```ts +import { IgxDialogComponent } from 'igniteui-angular/dialog'; + +public onSignIn(event: SubmitEvent, dialog: IgxDialogComponent) { + event.preventDefault(); + // Send the credentials. + dialog.close(); +} +``` + + + + + +### Position and Animation + +By default, the Angular Dialog opens in the center of the page with a fade animation. Set to change the position and the animations. The dialog uses a global position strategy, so only `horizontalDirection` and `verticalDirection` change its position, and the settings that you leave out keep their default values: + +```ts +import { slideInTop, slideOutTop } from 'igniteui-angular/animations'; +import { HorizontalAlignment, PositionSettings, VerticalAlignment } from 'igniteui-angular/core'; + +public positionSettings: PositionSettings = { + horizontalDirection: HorizontalAlignment.Center, + verticalDirection: VerticalAlignment.Top, + openAnimation: slideInTop, + closeAnimation: slideOutTop +}; +``` + +```html + + ... + +``` + +The dialog is modal by default: it shows a backdrop, and the backdrop blocks clicks on the page. Set to `false` to show the dialog without a backdrop and keep the page interactive. To change the overlay settings for a single opening, pass them to `open()`. The settings that you pass override the defaults of the dialog for that opening only and don't change its properties: + +```ts +this.dialog.open({ modal: false, closeOnOutsideClick: true }); +``` + + + +### Do/Don't + +The dialog's title and button labels work together to communicate the purpose of the dialog and the outcome of each action. Clear wording in both helps users understand what they are confirming and make decisions with confidence. + + + + +Use a specific title and button labels that clearly state the action and its outcome, so users know exactly what they are confirming. + + + + +Avoid vague titles and ambiguous labels like "Yes/No" — they don't tell users what will actually happen and lead to confusion and mistakes. + + + + + + + +When designing a custom Dialog, place all action buttons in the dialog's dedicated button area, keeping the body section for content only. + + + + +When designing a custom Dialog, avoid placing buttons in the body section and use the existing dialog buttons for your actions instead. + + + + +## Properties + +The {Platform} Dialog exposes the following properties. See the API reference for the complete type definitions. + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| | `string` | — | The text of the dialog header. The `title` slot takes precedence over it. | +| | `boolean` | `false` | Whether the dialog is open. A change opens or closes the dialog without the animations and the closing events. | +| | `boolean` | `false` | Whether the default OK button is hidden when the `footer` slot is empty. | +| | `boolean` | `false` | Whether the dialog stays open when the user presses Escape. | +| | `boolean` | `false` | Whether a click on the backdrop closes the dialog. | +| | `string \| undefined` | `undefined` | The `value` of the native button that submitted a form with `method="dialog"`. You can also set it in code. | + + + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| | `string` | — | The text of the dialog header. The `title` slot takes precedence over it. | +| | `bool` | `false` | Whether the dialog is open. A change opens or closes the dialog without the animations and the closing events. | +| | `bool` | `false` | Whether the default OK button is hidden when the `footer` slot is empty. | +| | `bool` | `false` | Whether the dialog stays open when the user presses Escape. | +| | `bool` | `false` | Whether a click on the backdrop closes the dialog. | +| | `string` | — | The name of a registered JavaScript function that handles the closing event in the browser and can cancel it. | + + + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| | `boolean` | `false` | Whether the dialog is open. Supports two-way binding. | +| | `string` | `''` | The text of the dialog header. When set, the projected title is ignored. | +| | `string` | `''` | The text of the dialog body. When set, the projected content is ignored. | +| | `string` | `''` | The text of the left built-in button, which renders only when the label is set. | +| | `string` | `''` | The text of the right built-in button, which renders only when the label is set. | +| | `IgxButtonType` | `'flat'` | The variant of the left built-in button. | +| | `IgxButtonType` | `'flat'` | The variant of the right built-in button. | +| | `string` | `''` | The ripple color of the left built-in button. | +| | `string` | `''` | The ripple color of the right built-in button. | +| | `boolean` | `true` | Whether the dialog closes when the user presses Escape. | +| | `boolean` | `false` | Whether a click outside the dialog closes it. | +| | `boolean` | `true` | Whether the dialog shows a backdrop that blocks clicks on the page. | +| | `boolean` | `true` | Whether Tab and Shift + Tab keep the focus inside the dialog. | +| | `PositionSettings` | — | The position and the animations of the dialog. Centered with a fade animation by default. | +| | `string` | — | Read-only. The ARIA role of the dialog, which depends on the built-in buttons. | +| | `string` | — | Read-only. The `id` that `aria-labelledby` of the dialog refers to. | + + + +## Methods + + + +The {Platform} Dialog exposes the following methods. They don't emit the closing events. + +| Method | Description | +| --- | --- | +| | Opens the dialog with the open animation. Returns a promise that resolves to `false` when the dialog is already open. | +| | Closes the dialog with the close animation. Returns a promise that resolves to `false` when the dialog is already closed. | +| | Opens the dialog when it's closed and closes it when it's open. | + + + + + +The {Platform} Dialog exposes the following methods. They don't raise `Closing` and `Closed`. + +| Method | Description | +| --- | --- | +| | Opens the dialog with the open animation. Returns `false` when the dialog is already open. | +| | Closes the dialog with the close animation. Returns `false` when the dialog is already closed. | +| | Opens the dialog when it's closed and closes it when it's open. | + + + + + +The Angular Dialog exposes the following methods. They emit the opening and the closing events. + +| Method | Description | +| --- | --- | +| | Opens the dialog. Accepts optional overlay settings that override the defaults of the dialog for this opening. | +| | Closes the dialog. | +| | Opens the dialog when it's closed and closes it when it's open. | + + + +## Events + +The {Platform} Dialog emits the following events. + + + +| Name | Type | Description | +| --- | --- | --- | +| `igcClosing` | `CustomEvent``EventCallback` | Emitted before the dialog closes when the user presses Escape, clicks the backdrop, clicks the default OK button, or submits a form with `method="dialog"`. Cancel it to keep the dialog open through `ClosingScript`. | +| `igcClosed` | `CustomEvent``EventCallback` | Emitted after the dialog closes and its close animation ends, for the same user actions. | + + + + + +| Name | Description | +| --- | --- | +| | Emitted with `IDialogCancellableEventArgs` before the dialog opens. Set `cancel` to keep the dialog closed. | +| | Emitted with `IDialogEventArgs` after the dialog opens and its open animation ends. | +| | Emitted with `IDialogCancellableEventArgs` before the dialog closes. Set `cancel` to keep the dialog open. The `event` argument holds the keyboard or the pointer event that closes the dialog. | +| | Emitted with `IDialogEventArgs` after the dialog closes and its close animation ends. | +| | Emitted with `IDialogEventArgs` when the user clicks the left built-in button. Doesn't close the dialog. | +| | Emitted with `IDialogEventArgs` when the user clicks the right built-in button. Doesn't close the dialog. | + + + +## Styling + +The {Platform} Dialog takes its colors from the theme. Change them with the following CSS variables: + +| Variable | What it changes | +| --- | --- | +| `--ig-dialog-background` | The background of the dialog. | +| `--ig-dialog-title-color` | The text color of the title. | +| `--ig-dialog-message-color` | The text color of the message and the content. | +| `--ig-dialog-border-color` | The border color of the dialog. | +| `--ig-dialog-border-radius` | The corner radius of the dialog. | +| `--ig-dialog-elevation` | The shadow of the dialog. | +| `--ig-dialog-backdrop` | The color of the backdrop behind the open dialog. || `--ig-overlay-background-color` | The color of the backdrop behind a modal dialog. The overlay theme sets this variable. | + + + +The `igc-dialog` element exposes the following CSS parts: + +| Part | What it styles | +| --- | --- | +| `base` | The native `dialog` element. | +| `title` | The header that holds the title. | +| `content` | The section that holds the message and the content. | +| `footer` | The footer that holds the action buttons. | +| `backdrop` | The backdrop behind the open dialog. | + + + +### Sass Theming + +When you modify a primary property, all related dependent properties are automatically updated to reflect the change. The primary parameter of the `dialog-theme` function is `$background`, from which the theme derives the title, the message, and the border colors. Create a theme with the function and include it with the `tokens()` mixin, which emits the matching `--ig-dialog-*` variables in the scope where you include it. + + + +```scss +@use "igniteui-angular/theming" as *; + +$custom-dialog-theme: dialog-theme( + $background: #011627, + $border-radius: 12px +); + +:host { + @include tokens($custom-dialog-theme); +} +``` + + + + + +The Sass functions come from the `igniteui-theming` package. See the [Theming](../themes/overview.mdx) topic for the Sass setup. + +```scss +@use "igniteui-theming" as *; + +$custom-dialog-theme: dialog-theme( + $background: #011627, + $border-radius: 12px +); + +:root { + @include tokens($custom-dialog-theme); +} +``` + + + +### CSS Variables + +Set the CSS variables on a Dialog or on a container when you need local styling without a Sass build step: + +```css +.welcome-dialog { + --ig-dialog-background: #011627; + --ig-dialog-title-color: #ffffff; + --ig-dialog-border-radius: 12px; +} +``` + + + +Use the CSS parts for other styles: + +```css +igc-dialog::part(title) { + font-weight: 600; +} + +igc-dialog::part(footer) { + gap: 16px; +} +``` + + + + + + + + + + + + + + + +### Styling with Tailwind + +You can style the {Platform} Dialog with Tailwind arbitrary properties that set the `--ig-dialog-*` CSS variables. Make sure to [set up Tailwind](../themes/misc/tailwind-classes.mdx)[set up Tailwind](../themes/tailwind.mdx) first. + + + +```html + + ... + +``` + + + + + +```html + + ... + +``` + + + + + +```tsx + + ... + +``` + + + + + +```razor + + ... + +``` + + + + + + + + + + + + + + + +## Accessibility + +The {Platform} Dialog shows its content in a modal window that users reach and leave with the keyboard. This section lists what the dialog renders and handles, as its template and event handlers define it. + +### Keyboard Interaction + + + +The {Platform} Dialog opens its native `dialog` element with `showModal()` and closes it with `close()`, so the browser manages the focus: + +- When the dialog opens, the focus moves to the first focusable element in the dialog, in DOM order: a control in the content, a button in the `footer` slot, or the default OK button. When the dialog has no focusable elements, the focus moves to the dialog itself. +- While the dialog is open, the rest of the page is inert, so the keyboard and the pointer can't reach it. +- When the dialog closes, the focus returns to the element that had it before the dialog opened. + +The following keys work while the dialog is open: + +| Key | Action | +| --- | --- | +| Tab / Shift + Tab | Moves the focus to the next or the previous focusable element in the dialog. The dialog doesn't handle these keys: the inert page makes the browser move the focus from the last element in the dialog to the browser controls and then back to the first element. | +| Escape | The browser sends a `cancel` event to the native `dialog`. The {Platform} Dialog prevents the native close, emits the closing event, and closes when you don't cancel that event. With `keepOpenOnEscape`, the dialog stays open, and when the browser closes the native `dialog` anyway, for example on a repeated Escape, the dialog opens it again. | +| Enter / Space | Activates the focused button. The default OK button closes the dialog and emits the closing events. | + +The {Platform} Dialog also handles these pointer and form actions: + +- A click on the native `dialog` outside its box, which is a click on the backdrop, closes the dialog when `closeOnOutsideClick` is set. The dialog checks the pointer position, so a press inside the dialog followed by a release on the backdrop also closes it. +- A `submit` event from a form with `method="dialog"` in the default slot closes the dialog, unless you prevent the `submit` event or cancel the closing event. + + + + + +The Angular Dialog manages the focus as follows: + +- When the dialog opens with built-in buttons, each button gets the `igxFocus` directive bound to `isOpen`, so the right button gets the focus, or the left button when it's the only one. +- When the dialog opens without built-in buttons, the focus moves to the `div.igx-dialog` container. To focus the first control in the content instead, add `[igxFocus]="dialog.isOpen"` to it. +- While the dialog is open, the `igxFocusTrap` directive on the `div.igx-dialog` container handles Tab and Shift + Tab. +- When the dialog closes, the focus doesn't return to the element that opened it. + +The following keys work while the dialog is open: + +| Key | Action | +| --- | --- | +| Tab | Moves the focus to the next focusable element in the dialog, and from the last one to the first. | +| Shift + Tab | Moves the focus to the previous focusable element in the dialog, and from the first one to the last. | +| Escape | Closes the dialog and emits `closing` and `closed` when `closeOnEscape` is `true`. The overlay service listens for Escape on the whole document, so the key works wherever the focus is, and it closes only the topmost open overlay. | +| Enter / Space | Activates the focused button. A built-in button emits `leftButtonSelect` or `rightButtonSelect` and doesn't close the dialog. | + +The focus trap works only when `focusTrap` is `true`, and it handles Tab and Shift + Tab as follows: + +- It finds the focusable elements in the dialog with the `a[href], button, input, textarea, select, details, [tabindex]:not([tabindex="-1"])` selector. It skips disabled elements and the content of elements with `aria-hidden="true"`, and it doesn't look into the shadow roots of web components. +- It moves the focus in DOM order, so it ignores positive `tabindex` values, and it wraps from the last element to the first and back. +- When the dialog has no focusable elements, it keeps the focus on the `div.igx-dialog` container. + +The Angular Dialog also handles these pointer actions: + +- In a modal dialog, a click on the backdrop closes the dialog when `closeOnOutsideSelect` is `true`. A press inside the dialog followed by a release on the backdrop also counts as a click on the backdrop. +- In a dialog with `isModal` set to `false`, a click anywhere outside the dialog closes it when `closeOnOutsideSelect` is `true`. +- The dialog stops the propagation of the clicks inside it, so click handlers on the document don't receive them. + + + +### Screen Readers / ARIA + + + +The {Platform} Dialog renders the following roles and attributes: + +| Element | Role | Attributes | +| --- | --- | --- | +| `div[part="backdrop"]` | — | `aria-hidden="true"` while the dialog is closed. The element is empty and decorative. | +| `dialog[part="base"]` | `dialog` | `aria-labelledby` that points to the `title` part. When you set `aria-label` on the `igc-dialog` element, the dialog gets that `aria-label`, and `aria-labelledby` holds the label text instead of the `id` of the `title` part, so the `aria-label` names the dialog. | +| `header[part="title"]` | — | The `id` that `aria-labelledby` points to. Hidden when the dialog has no title. | +| The default OK button | `button` | The name "OK". | + +The {Platform} Dialog exposes the following information to assistive technology: + +- While the dialog is open, it's a modal `dialog`, and the content of the page outside it isn't in the accessibility tree. While the dialog is closed, the dialog isn't in the accessibility tree. +- The dialog takes its accessible name from the `title` property or the `title` slot. An `aria-label` on the `igc-dialog` element takes precedence over the title, and a dialog without a title or an `aria-label` has no accessible name. +- The dialog doesn't set `aria-describedby`, so the message and the content aren't its accessible description. +- The dialog doesn't use a live region. Assistive technology finds the open dialog through the focus, which moves into it. + + + + + +The Angular Dialog renders the following roles and attributes: + +| Element | Role | Attributes | +| --- | --- | --- | +| `igx-dialog` | — | `id`, `igx-dialog-0` and up by default, and `tabindex="-1"`. | +| `div.igx-overlay__wrapper--modal` | — | `popover="manual"`, which renders the open dialog in the top layer of the page. | +| `div.igx-dialog` | — | `tabindex="0"`, and `aria-hidden="true"` while the dialog is closed. | +| `div.igx-dialog__window` | `dialog` with two built-in buttons, `alertdialog` with one, `alert` without built-in buttons | `aria-labelledby` that points to the `titleId`. | +| `div.igx-dialog__window-title` | — | The `id` that `aria-labelledby` points to, set to the `titleId`. Rendered when you set `title`. | +| The built-in buttons | `button` | `type="button"` and the name from `leftButtonLabel` or `rightButtonLabel`. | + +The Angular Dialog exposes the following information to assistive technology: + +- The role of the dialog depends on the built-in buttons, and the `role` property is read-only. A custom dialog without built-in buttons, such as a sign-in form, has the `alert` role. +- The dialog takes its accessible name from the `title` property. A projected `igx-dialog-title` doesn't get the `titleId`, so a dialog with a projected title has no accessible name unless you bind `[id]="dialog.titleId"` on the title. +- The dialog doesn't set `aria-modal`, and the top layer doesn't make the rest of the page inert, so assistive technology can still reach the page behind a modal dialog. +- The dialog doesn't set `aria-describedby`, so the message and the content aren't its accessible description. +- While the dialog is closed, its container has `aria-hidden="true"` and is hidden. + + + +### Accessibility Compliance + +Infragistics documents {ProductName} accessibility support for Section 508 and WCAG 2.1 guideline areas in the [Accessibility Compliance](../interactivity/accessibility-compliance.mdx) topic. + +| Criterion | How the component complies | +| --- | --- | +| [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships) | The role of the dialog exposes the window, and `aria-labelledby` links the dialog to its title. The role depends on the built-in buttons. | +| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG21/Understanding/keyboard) | Tab and Shift + Tab reach every control in the dialog, Enter and Space activate the buttons, and Escape closes the dialog. | +| [2.1.2 No Keyboard Trap](https://www.w3.org/WAI/WCAG21/Understanding/no-keyboard-trap) | Escape closes the dialog by default, so keyboard users can leave it with a standard key. | +| [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG21/Understanding/focus-order) | The focus moves into the dialog when it opens and returns to the previously focused element when it closes.The focus moves into the dialog when it opens, to a built-in button or to the dialog container, and the focus trap keeps Tab and Shift + Tab inside the dialog while it's open. | +| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value) | The dialog exposes its role and a name from its title. | + +Your responsibilities: + +- Give every dialog a title that names its task, as the [Do/Don't](#dodont) guidance shows. For a dialog without a title, set `aria-label` on the dialog. For a projected title, bind `[id]="dialog.titleId"` on it. +- Keep a button that closes the dialog, especially when you turn off closing on Escape. +- When you override the theme colors, keep a contrast ratio of at least 4.5:1 between the text and the background of the dialog, as [1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum) requires. +- Return the focus to the element that opened the dialog in the handler of `closed`. + +## Troubleshooting + +These are the {Platform} Dialog problems that come up most often, with their causes and fixes. + + + +### Why is returnValue empty after the user submits the form? + +The {Platform} Dialog sets `returnValue` from the submitter of the form, and only a native `button` or `input` element is a submitter. An Ignite UI Button submits the form without a submitter, so `returnValue` keeps its previous value. Use a native submit button, or set `returnValue` in the click handler of the Ignite UI Button before the form is submitted. + + + + + +### Why does Show() throw an error? + +The `Show`, `Hide`, and `Toggle` methods are the synchronous versions of `ShowAsync`, `HideAsync`, and `ToggleAsync`. The dialog methods in the browser return a promise, so on Blazor WebAssembly the synchronous calls throw an exception although the dialog opens or closes, and on Blazor Server they fail ([igniteui-blazor#512](https://github.com/IgniteUI/igniteui-blazor/issues/512)). Use the `Async` methods instead. + + + + + +### Why does a screen reader read my custom dialog as an alert? + +The Angular Dialog sets its role from the built-in buttons, and a dialog without `leftButtonLabel` and `rightButtonLabel` gets the `alert` role. The `role` property is read-only. When the dialog only confirms or cancels an action, use the built-in buttons, which give it the `dialog` or the `alertdialog` role. + +### Why doesn't a change to closeOnEscape take effect? + +The Angular Dialog passes `closeOnEscape`, `closeOnOutsideSelect`, and `isModal` to the overlay when it opens, so a change while the dialog is open applies the next time it opens ([igniteui-angular#12537](https://github.com/IgniteUI/igniteui-angular/issues/12537)). To change the behavior of an open dialog, cancel the `closing` event instead. + + + +### Known Limitations + + + +- The `command` and `commandfor` attributes work only in browsers that support the [Invoker Commands API](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API). +- The `message` slot limits its content to a width of 40 characters. + + + + + +- The `Open` parameter doesn't change when the user closes the dialog, and the Blazor Dialog has no `OpenChanged` callback. +- The `Closing` callback can't cancel the closing. Use `ClosingScript`, as described in [Closing on Escape and Outside Click](#closing-on-escape-and-outside-click). +- The `ReturnValue` parameter doesn't reach the dialog in the browser, and it doesn't change when a form sets the return value ([igniteui-blazor#300](https://github.com/IgniteUI/igniteui-blazor/issues/300)). + + + + + +- The dialog doesn't return the focus to the element that opened it when it closes. +- The modal dialog doesn't make the rest of the page inert for assistive technology. +- The focus trap moves the focus in DOM order and ignores positive `tabindex` values ([igniteui-angular#13299](https://github.com/IgniteUI/igniteui-angular/issues/13299)). +- The dialog stops the propagation of the clicks inside it, so a third-party menu in the dialog that closes on document clicks stays open ([igniteui-angular#13849](https://github.com/IgniteUI/igniteui-angular/issues/13849)). +- The `minSize` of the position settings has no effect, because the dialog uses a global position strategy. + + + +## API References + +The {Platform} Dialog API reference lists the complete API surface for the target platform. + + + +- + + + + + +- +- +- +- + + + +## Dependencies + +The {Platform} Dialog requires a theme to apply its colors and sizes. See the framework-specific setup in [**Getting Started**](../general/getting-started.mdx)[**Getting Started**](../general-getting-started.mdx). + + + +The Angular Dialog renders through the overlay service, which also draws the backdrop of a modal dialog. The built-in buttons use the `igxButton` and `igxRipple` directives. + + + + + +The registration of the `IgcDialogComponent` also registers the `igc-button` element of the default OK button. Register the components that you place in the dialog, such as the Input, separately. + + + + + +Registering the modules of the components that you place in the dialog, such as the `IgbButtonModule` and the `IgbInputModule`, is optional as well: each component loads its client resources the first time it renders (see [Component Modules](../general-getting-started.mdx#component-modules)). + + + +## Additional Resources + +The following resources provide more {Platform} Dialog guidance and project support: + +- [Dialog - Design System Component](https://www.infragistics.com/products/indigo-design/help/components/dialog) +- [{ProductName} **Forums**]({ForumsLink}) +- [{ProductName} **GitHub**]({GithubLink}) + +## Related Components + +The {Platform} Dialog blocks the page until the user completes or closes it. Use these components when the message doesn't need to interrupt the user: + +- [Banner](../banner.mdx)[Banner](./banner.mdx) - Use Banner for an important message that stays on the page until the user dismisses it. +- [Snackbar](../snackbar.mdx)[Snackbar](./snackbar.mdx) - Use Snackbar for a brief message about an operation, with an optional action. +- [Toast](../toast.mdx)[Toast](./toast.mdx) - Use Toast for a brief message that disappears on its own and needs no action. + +## FAQ + + + + When `closeOnOutsideSelect` is `true`, the Angular Dialog treats a press inside the dialog followed by a release outside it as a click outside, so it closes. Leave `closeOnOutsideSelect` off for a dialog with input fields or text that users select, or cancel the `closing` event when the press started inside the dialog.When `closeOnOutsideClick` is set, the browser reports a press inside the {Platform} Dialog followed by a release on the backdrop as a click outside the dialog, so the dialog closes. Leave `closeOnOutsideClick` off for a dialog with input fields or text that users select, or cancel the closing event when the press started inside the dialog. + + + The Angular Dialog sizes to its content and has no width property, and the `minSize` of its position settings has no effect with the global position strategy that the dialog uses. Set the width on an element in the content, such as a `div` that wraps the content. The `message` text of the Angular Dialog is limited to a width of 40 characters.Set the width of the `base` part, for example `igc-dialog::part(base) { width: 600px; }`, because the {Platform} Dialog otherwise sizes to its content. The `message` slot of the {Platform} Dialog limits its content to a width of 40 characters, so place wide content in the default slot. + + + The Angular Dialog doesn't return the focus to the element that opened it, so the focus moves to the page body. Focus that element yourself in the handler of `closed`, for example `(closed)="openButton.focus()"` with an `#openButton` template reference variable on the button that opens the dialog.The browser returns the focus to the element that had it before the {Platform} Dialog opened, which is usually the button that opened the dialog. While the {Platform} Dialog is open, the rest of the page is inert, so the focus can't move to the page. + + + It doesn't. The Angular Dialog emits `closing` and `closed` as Angular outputs, which don't bubble, so a component in the dialog doesn't run the handlers of the dialog. Bind the events of the inner component on that component.The Select, the Combo, and other components that open and close emit their own `igcClosing` and `igcClosed` events, which bubble to the {Platform} Dialog. Check that the target of the event is the dialog before you handle it, as the examples in [Closing on Escape and Outside Click](#closing-on-escape-and-outside-click) do. The `Closing` and `Closed` callbacks of the Blazor Dialog don't carry the target, so check it in a `ClosingScript` or `ClosedScript` function. + + diff --git a/docs/xplat/src/content/en/toc.json b/docs/xplat/src/content/en/toc.json index aab8e14594..8c6d3a78f5 100644 --- a/docs/xplat/src/content/en/toc.json +++ b/docs/xplat/src/content/en/toc.json @@ -3557,11 +3557,9 @@ ] }, { - "exclude": [ - "Angular" - ], "name": "Dialog", "href": "notifications/dialog.mdx", + "updated": true, "include": [ "Web" ]