Web Components - Dialog

A dialog component presents content to the user. Unlike modal it doesn't prevent the user from interacting with other content on the page.

Set-up

import { provideDesignSystem, alphaDialog } from '@genesislcap/alpha-design-system';

provideDesignSystem().register(alphaDialog());

Attributes

When you declare an <alpha-dialog>, you can provide the following attribute:

Name	Type	Description
position	string	Places the dialog to the right, centre or left of the screen. Default: centre
show-close-icon	boolean	Enables the close button on the top-right corner. Default: true

note

Unlike the modal component, the dialog component is not positioned in a layer in front of other components. It appears where it is declared. Any change of positioning must be addressed using css.

Methods

When declaring an alpha-dialog component, the following methods are available:

Name	Description
show()	Shows the dialog
close()	Closes the dialog
onShowCallback()	Callback that runs before open the dialog
onCloseCallback()	Callback that runs after close the dialog

By default, the dialog-component starts closed.

Usage

Below is the standard declaration of the dialog:

<alpha-dialog>
    This is a dialog
</alpha-dialog>

Interaction

In order to interact with the dialog component, you need to use the available methods. To do that, import dialog from @genesislcap/alpha-design-system:

import { Dialog as alphaDialog } from '@genesislcap/alpha-design-system';

note

If you are using foundation-zero, then you need to import using @genesislcap/foundation-zero

After that, you need to define the local variable to be referred to, in this case localDialog:

export class TEMPLATE extends FASTElement {
    ...
    localDialog: alphaDialog;
    ...
}

Now that you have your local variable, you can use the directive ref to link your component to this variable:

import {... , ref} from '@microsoft/fast-element';
...
export const yourTemplate = html<Template>`
    ...
    <alpha-dialog ${ref('localDialog')}>
    This is a dialog
    </alpha-dialog>
    }

If you are not familiar with the ref directive, take a look at the Microsoft Fast documentation.

From this point, you can use both show() and close() as methods of localDialog.

Callbacks

The dialog provides two callbacks onShowCallback() and onCloseCallback(). To work with them, you need to use them inside the connectedCallback(). Below is an example using the variable localDialog that was defined earlier.

connectedCallback(){
    super.connectedCallback()
    ...

    this.localDialog.onShowCallback = () => {
        //Write your code here
    }
    
    this.localDialog.onCloseCallback = () => {
        //Write your code here
    }
    
    ...
}

Examples

Below we have three practical examples where we create a dialog, plus buttons to open and close it:

• Create a dialog positioned to the left with the close-icon desabled:

<alpha-dialog position="left" show-close-icon="false">
    This is a dialog
</alpha-dialog>

• Create a button to open a dialog:

import {... , ref} from '@microsoft/fast-element';
import {sync} from '@genesislcap/foundation-utils';
...
export const yourTemplate = html<Template>`
    ...
    <alpha-button @click=${x => x.localDialog.show()}></alpha-button>
    <alpha-dialog ${ref('localDialog')}>
        This is a dialog
    </alpha-dialog>
    }

• Create a button inside the dialog to close it:

import {... , ref} from '@microsoft/fast-element';
import {sync} from '@genesislcap/foundation-utils';
...
export const yourTemplate = html<Template>`
    ...
    <alpha-button @click=${x => x.localDialog.show()}>Open dialog</alpha-button>
    <alpha-dialog ${ref('localDialog')}>
        This is a dialog
        <alpha-button @click=${x => x.localDialog.show()}>Close dialog</alpha-button>
    </alpha-dialog>
    }

Use cases

• Confirmation pop-ups
• Alerts
• Forms submissions
• Contextual information

Additional resources

• W3C Component Aria Practices