Coral.Dialog

Current Version: 1.5.10
Note:Any Coral CSS classes and attributes not explicitly mentioned in the public documentation are private and subject to change. Their direct use is not recommended and at high risk of breaking after subsequent updates of CoralUI library. For technical details of how to use Coral safely, please refer to the CoralUI Architecture.
Github: @coralui/coralui-component-dialog

JavaScript Examples

JS Class Initialization

Use the Coral.Dialog constructor to instantiate a Coral.Dialog.

<script>
  var dialog = new Coral.Dialog().set({
    id: 'myDialog',
    header: {
      innerHTML: 'This Dialog is Awesome'
    },
    content: {
      innerHTML: '<coral-checkbox id="agree">I Agree</coral-checkbox>'
    },
    footer: {
      innerHTML: '<button is="coral-button" variant="primary" coral-close>Ok</button>'
    }
  });
  document.body.appendChild(dialog);
</script>

Show a Coral.Dialog

The following is an example of how to show a Coral.Dialog.

<script>
  function showDialog() {
    var dialog = document.querySelector('#myDialog');
    dialog.show();
  }
</script>

Handling user interaction

To prevent a dialog from being hidden (for example, until a form passes validation), call event.preventDefault() in any listener to the coral-overlay:beforeclose event.

Open and close the dialog using the "Show a Dialog" example above to see logged events.

<script>
  var dialog = document.querySelector('#myDialog');
  dialog.on('coral-overlay:open', function(event) {
    $('#eventLog').log('Dialog opened.');
  });
  dialog.on('coral-overlay:close', function(event) {
    $('#eventLog').log('Dialog closed.');
  });
  dialog.on('coral-overlay:beforeclose', function(event) {
    if (!document.querySelector('#agree').checked) {
      // Stop the dialog from hiding
      event.preventDefault();
    
      $('#eventLog').log('Dialog will NOT be closed.');
    }
    else {
      $('#eventLog').log('Dialog will be closed.');
    }
  });
</script>

Log

Handling user interaction programmatically

Create a Coral.Dialog with two buttons in the footer.

The Cancel button will have the [coral-close] attribute so it dismisses the dialog.

The Accept button will have a specific ID that we'll listen for clicks on.

<script>
  var dialog = new Coral.Dialog().set({
    id: 'buyDialog',
    header: {
      innerHTML: 'Dialog Example'
    },
    content: {
      innerHTML: 'You are going to buy stuff, if you accept this message'
    },
    footer: {
      innerHTML: '<button id="cancelButton" is="coral-button" variant="default" coral-close>Cancel</button><button id="acceptButton" is="coral-button" variant="primary">Accept</button>'
    }
  });
  document.body.appendChild(dialog);
</script>

Listen for the coral-overlay:close event to know when the dialog has been dismissed.

Listen for the click event on the accept button to know when the user wants to proceed.

<script>
  var dialog = document.querySelector('#buyDialog');
  dialog.on('coral-overlay:close', function (event) {
    $('#eventLogBuy').log('Closing dialog.');
  });
  dialog.on('click', '#acceptButton', function() {
    $('#eventLogBuy').log('Accepting the deal');
    dialog.hide();
  });
</script>

Log

Behavior

Keyboard Controls

When the modal is visible, pressing the escape key will dismiss the top most modal.

Focus Behavior

When shown, the modal will focus on itself, showing no border. Pressing Tab will move to the first focusable element, usually the close button. Pressing Shift + Tab will move to the last focusable item in the modal, usually the last button.

When Tab is pressed on the last focusable item, focus will shift to the first focusable item. When Shift + Tab is pressed on the first focusable item, focus will shift to the last focusable item.

When hidden, the modal will return focus to the element that was previously focused on the page.

Coral.Dialog API

Constructor

JavaScript:

new Coral.Dialog() or document.createElement('coral-dialog')

HTML Tag:

<coral-dialog>

Extends

Sub-components

Static Properties

Coral.Dialog.backdrop {String}

Dialog backdrop types.

Properties:

Name Type Value Description
NONE String none No backdrop.
MODAL String modal A backdrop that hides the dialog when clicked.
STATIC String static A backdrop that does not hide the dialog when clicked.

Coral.Dialog.closable {String}

Boolean enumeration for dialog closable state.

Properties:

Name Type Value Description
ON String on Show a close button on the dialog and close the dialog when clicked.
OFF String off Do not show a close button. Elements with the coral-close attribute will still close the dialog.

Coral.Dialog.interaction {String}

Boolean enumeration for dialog keyboard interaction state.

Properties:

Name Type Value Description
ON String on Keyboard interaction is enabled.
OFF String off Keyboard interaction is disabled.

Coral.Dialog.variant {String}

Dialog variants.

Properties:

Name Type Value Description
DEFAULT String default A dialog with the default, gray header and no icon.
ERROR String error A dialog with a red header and warning icon, indicating that an error has occurred.
WARNING String warning A dialog with an orange header and warning icon, notifying the user of something important.
SUCCESS String success A dialog with a green header and checkmark icon, indicates to the user that an operation was successful.
HELP String help A dialog with a blue header and question mark icon, provides the user with help.
INFO String info A dialog with a blue header and info icon, informs the user of non-critical information.

Instance Properties

instance.backdrop {Coral.Dialog.backdrop}

The backdrop configuration for this dialog.
Default Value:
  • Coral.Dialog.backdrop.MODAL
HTML Attribute:
  • backdrop

instance.closable {Coral.Dialog.closable}

Reflected
Whether the dialog should have a close button.
Default Value:
  • Coral.Dialog.closable.OFF
HTML Attribute:
  • closable

instance.content {HTMLElement}

The dialog's content element.

instance.focusOnShow {Coral.mixin.overlay.focusOnShow | HTMLElement | String}

Whether to focus the overlay, when opened or not. By default the overlay itself will get the focus. It also accepts an instance of HTMLElement or a selector like ':first-child' or 'button:last-of-type'. If the selector returns multiple elements, it will focus the first element inside the overlay that matches the selector.
Inherited From:
Default Value:
HTML Attribute:
  • focusonshow

instance.footer {HTMLElement}

The dialog's footer element.

instance.fullscreen {Boolean}

Reflected
Whether the dialog should be displayed full screen (without borders or margin).
Default Value:
  • false
HTML Attribute:
  • fullscreen

instance.header {HTMLElement}

The dialog's header element.

instance.hidden {Boolean}

Reflected
Whether this component is hidden or not.
Inherited From:
Default Value:
  • false
HTML Attribute:
  • hidden

instance.icon {String}

The dialog's icon.
Default Value:
  • ""
HTML Attribute:
  • icon

instance.interaction {Coral.Dialog.interaction}

Whether keyboard interaction is enabled.
Default Value:
  • Coral.Dialog.interaction.ON

instance.movable {Boolean}

Reflected
Whether the dialog can moved around by dragging the title.
Default Value:
  • false
HTML Attribute:
  • movable

instance.open {Boolean}

Reflected
Whether this overlay is open or not.
Inherited From:
Default Value:
  • false
HTML Attribute:
  • open

instance.returnFocus {Coral.mixin.overlay.returnFocus}

Whether to return focus to the previously focused element when closed.
Default Value:
  • Coral.mixin.overlay.returnFocus.ON
HTML Attribute:
  • returnfocus

instance.trapFocus {Coral.mixin.overlay.trapFocus}

Whether to trap tabs and keep them within the overlay.
Default Value:
  • Coral.mixin.overlay.trapFocus.ON
HTML Attribute:
  • trapfocus

instance.variant {Coral.Dialog.variant}

The dialog's variant.
Default Value:
  • Coral.Dialog.variant.DEFAULT
HTML Attribute:
  • variant

Methods

instance.center

Centers the dialog in the middle of the screen.
Returns:
this, chainable. {Coral.Dialog}

instance.get

Get the value of a property.
Parameters:
Name Type Description
property String The name of the property to fetch the value of.
Returns:
Property value. {*}
Inherited From:

instance.hide

Hide this component.
Returns:
this, chainable {Coral.Component}
Inherited From:

instance.off

Remove an event listener.
Parameters:
Name Type Optional Description
eventName String No
 The event name to stop listening for.
selector String Yes
 The selector that was used for event delegation.
func function No
 The function that was passed to on().
useCapture Boolean Yes
 Only remove listeners with useCapture set to the value passed in.
Returns:
this, chainable. {Coral.Component}
Inherited From:

instance.on

Add an event listener.
Parameters:
Name Type Optional Default Description
eventName String No
 The event name to listen for.
selector String Yes
 The selector to use for event delegation.
func function No
 The function that will be called when the event is triggered.
useCapture Boolean Yes
 Whether or not to listen during the capturing or bubbling phase.
Returns:
this, chainable. {Coral.Component}
Inherited From:

instance.remove

Non-destructively remove this element. It can be re-added by simply appending it to the document again. It will be garbage collected if there are no more references to it.
Inherited From:

instance.returnFocusTo

Set the element that focus should be returned to when the overlay is hidden.
Parameters:
Name Type Description
element HTMLElement The element to return focus to. This must be a DOM element, not a jQuery object or selector.
Returns:
this, chainable {Coral.Component}
Inherited From:

instance.set

Set a single property.
Parameters:
Name Type Description
property String The name of the property to set.
value * The value to set the property to.
silent Boolean If true, events should not be triggered as a result of this set.
Returns:
this, chainable. {Coral.Component}
Inherited From:

instance.show

Show this component.
Returns:
this, chainable {Coral.Component}
Inherited From:

instance.trigger

Trigger an event.
Parameters:
Name Type Optional Default Description
eventName String No
 The event name to trigger.
props Object Yes
 Additional properties to make available to handlers as event.detail.
bubbles Boolean Yes
 Set to false to prevent the event from bubbling.
cancelable Boolean Yes
 Set to false to prevent the event from being cancelable.
Returns:
CustomEvent object {CustomEvent}
Inherited From:

Events

coral-component:attached

Triggered when the component is attached to the DOM.
Callback Parameters:
Name Type Description
event Object Event object.
Inherited From:
Deprecated:
  • since 1.14.0, use MutationObserver instead.

    coral-component:detached

    Triggered when the component is detached to the DOM.
    Callback Parameters:
    Name Type Description
    event Object Event object.
    Inherited From:
    Deprecated:
    • since 1.14.0, use MutationObserver instead.

      coral-component:ready

      Triggerred when the component has been upgraded and is ready for use.
      Callback Parameters:
      Name Type Description
      event Object Event object.
      Inherited From:
      Deprecated:
      • since 1.9.0, use Coral.commons.ready() instead.

        coral-overlay:beforeclose

        Triggerred before the component is closed with hide() or instance.open = false.
        Callback Parameters:
        Name Type Description
        event Object

        Event object.

        Name Type Description
        event.preventDefault function Call to stop the overlay from closing.
        Inherited From:

        coral-overlay:beforeopen

        Triggerred before the component is opened with show() or instance.open = true.
        Callback Parameters:
        Name Type Description
        event Object

        Event object.

        Name Type Description
        event.preventDefault function Call to stop the overlay from opening.
        Inherited From:

        coral-overlay:close

        Triggerred after the component is closed with hide() or instance.open = false
        Callback Parameters:
        Name Type Description
        event Object Event object.
        Inherited From:

        coral-overlay:open

        Triggerred after the overlay is opened with show() or instance.open = true
        Callback Parameters:
        Name Type Description
        event Object Event object.
        Inherited From:

        Coral.Dialog.Header API

        Constructor

        JavaScript:

        new Coral.Dialog.Header() or document.createElement('coral-dialog-header')

        HTML Tag:

        <coral-dialog-header>

        Extends

        Instance Properties

        instance.hidden {Boolean}

        Reflected
        Whether this component is hidden or not.
        Inherited From:
        Default Value:
        • false
        HTML Attribute:
        • hidden

        Methods

        instance.get

        Get the value of a property.
        Parameters:
        Name Type Description
        property String The name of the property to fetch the value of.
        Returns:
        Property value. {*}
        Inherited From:

        instance.hide

        Hide this component.
        Returns:
        this, chainable {Coral.Component}
        Inherited From:

        instance.off

        Remove an event listener.
        Parameters:
        Name Type Optional Description
        eventName String No
        		 The event name to stop listening for.
        selector String Yes
        		 The selector that was used for event delegation.
        func function No
        		 The function that was passed to on().
        useCapture Boolean Yes
        		 Only remove listeners with useCapture set to the value passed in.
        Returns:
        this, chainable. {Coral.Component}
        Inherited From:

        instance.on

        Add an event listener.
        Parameters:
        Name Type Optional Default Description
        eventName String No
        		 The event name to listen for.
        selector String Yes
        		 The selector to use for event delegation.
        func function No
        		 The function that will be called when the event is triggered.
        useCapture Boolean Yes
        		 Whether or not to listen during the capturing or bubbling phase.
        Returns:
        this, chainable. {Coral.Component}
        Inherited From:

        instance.remove

        Non-destructively remove this element. It can be re-added by simply appending it to the document again. It will be garbage collected if there are no more references to it.
        Inherited From:

        instance.set

        Set a single property.
        Parameters:
        Name Type Description
        property String The name of the property to set.
        value * The value to set the property to.
        silent Boolean If true, events should not be triggered as a result of this set.
        Returns:
        this, chainable. {Coral.Component}
        Inherited From:

        instance.show

        Show this component.
        Returns:
        this, chainable {Coral.Component}
        Inherited From:

        instance.trigger

        Trigger an event.
        Parameters:
        Name Type Optional Default Description
        eventName String No
        		 The event name to trigger.
        props Object Yes
        		 Additional properties to make available to handlers as event.detail.
        bubbles Boolean Yes
        		 Set to false to prevent the event from bubbling.
        cancelable Boolean Yes
        		 Set to false to prevent the event from being cancelable.
        Returns:
        CustomEvent object {CustomEvent}
        Inherited From:

        Events

        coral-component:attached

        Triggered when the component is attached to the DOM.
        Callback Parameters:
        Name Type Description
        event Object Event object.
        Inherited From:
        Deprecated:
        • since 1.14.0, use MutationObserver instead.

          coral-component:detached

          Triggered when the component is detached to the DOM.
          Callback Parameters:
          Name Type Description
          event Object Event object.
          Inherited From:
          Deprecated:
          • since 1.14.0, use MutationObserver instead.

            coral-component:ready

            Triggerred when the component has been upgraded and is ready for use.
            Callback Parameters:
            Name Type Description
            event Object Event object.
            Inherited From:
            Deprecated:
            • since 1.9.0, use Coral.commons.ready() instead.

              Coral.Dialog.Content API

              Constructor

              JavaScript:

              new Coral.Dialog.Content() or document.createElement('coral-dialog-content')

              HTML Tag:

              <coral-dialog-content>

              Extends

              Instance Properties

              instance.hidden {Boolean}

              Reflected
              Whether this component is hidden or not.
              Inherited From:
              Default Value:
              • false
              HTML Attribute:
              • hidden

              Methods

              instance.get

              Get the value of a property.
              Parameters:
              Name Type Description
              property String The name of the property to fetch the value of.
              Returns:
              Property value. {*}
              Inherited From:

              instance.hide

              Hide this component.
              Returns:
              this, chainable {Coral.Component}
              Inherited From:

              instance.off

              Remove an event listener.
              Parameters:
              Name Type Optional Description
              eventName String No
              		 The event name to stop listening for.
              selector String Yes
              		 The selector that was used for event delegation.
              func function No
              		 The function that was passed to on().
              useCapture Boolean Yes
              		 Only remove listeners with useCapture set to the value passed in.
              Returns:
              this, chainable. {Coral.Component}
              Inherited From:

              instance.on

              Add an event listener.
              Parameters:
              Name Type Optional Default Description
              eventName String No
              		 The event name to listen for.
              selector String Yes
              		 The selector to use for event delegation.
              func function No
              		 The function that will be called when the event is triggered.
              useCapture Boolean Yes
              		 Whether or not to listen during the capturing or bubbling phase.
              Returns:
              this, chainable. {Coral.Component}
              Inherited From:

              instance.remove

              Non-destructively remove this element. It can be re-added by simply appending it to the document again. It will be garbage collected if there are no more references to it.
              Inherited From:

              instance.set

              Set a single property.
              Parameters:
              Name Type Description
              property String The name of the property to set.
              value * The value to set the property to.
              silent Boolean If true, events should not be triggered as a result of this set.
              Returns:
              this, chainable. {Coral.Component}
              Inherited From:

              instance.show

              Show this component.
              Returns:
              this, chainable {Coral.Component}
              Inherited From:

              instance.trigger

              Trigger an event.
              Parameters:
              Name Type Optional Default Description
              eventName String No
              		 The event name to trigger.
              props Object Yes
              		 Additional properties to make available to handlers as event.detail.
              bubbles Boolean Yes
              		 Set to false to prevent the event from bubbling.
              cancelable Boolean Yes
              		 Set to false to prevent the event from being cancelable.
              Returns:
              CustomEvent object {CustomEvent}
              Inherited From:

              Events

              coral-component:attached

              Triggered when the component is attached to the DOM.
              Callback Parameters:
              Name Type Description
              event Object Event object.
              Inherited From:
              Deprecated:
              • since 1.14.0, use MutationObserver instead.

                coral-component:detached

                Triggered when the component is detached to the DOM.
                Callback Parameters:
                Name Type Description
                event Object Event object.
                Inherited From:
                Deprecated:
                • since 1.14.0, use MutationObserver instead.

                  coral-component:ready

                  Triggerred when the component has been upgraded and is ready for use.
                  Callback Parameters:
                  Name Type Description
                  event Object Event object.
                  Inherited From:
                  Deprecated:
                  • since 1.9.0, use Coral.commons.ready() instead.

                    Coral.Dialog.Footer API

                    Constructor

                    JavaScript:

                    new Coral.Dialog.Footer() or document.createElement('coral-dialog-footer')

                    HTML Tag:

                    <coral-dialog-footer>

                    Extends

                    Instance Properties

                    instance.hidden {Boolean}

                    Reflected
                    Whether this component is hidden or not.
                    Inherited From:
                    Default Value:
                    • false
                    HTML Attribute:
                    • hidden

                    Methods

                    instance.get

                    Get the value of a property.
                    Parameters:
                    Name Type Description
                    property String The name of the property to fetch the value of.
                    Returns:
                    Property value. {*}
                    Inherited From:

                    instance.hide

                    Hide this component.
                    Returns:
                    this, chainable {Coral.Component}
                    Inherited From:

                    instance.off

                    Remove an event listener.
                    Parameters:
                    Name Type Optional Description
                    eventName String No
                    		 The event name to stop listening for.
                    selector String Yes
                    		 The selector that was used for event delegation.
                    func function No
                    		 The function that was passed to on().
                    useCapture Boolean Yes
                    		 Only remove listeners with useCapture set to the value passed in.
                    Returns:
                    this, chainable. {Coral.Component}
                    Inherited From:

                    instance.on

                    Add an event listener.
                    Parameters:
                    Name Type Optional Default Description
                    eventName String No
                    		 The event name to listen for.
                    selector String Yes
                    		 The selector to use for event delegation.
                    func function No
                    		 The function that will be called when the event is triggered.
                    useCapture Boolean Yes
                    		 Whether or not to listen during the capturing or bubbling phase.
                    Returns:
                    this, chainable. {Coral.Component}
                    Inherited From:

                    instance.remove

                    Non-destructively remove this element. It can be re-added by simply appending it to the document again. It will be garbage collected if there are no more references to it.
                    Inherited From:

                    instance.set

                    Set a single property.
                    Parameters:
                    Name Type Description
                    property String The name of the property to set.
                    value * The value to set the property to.
                    silent Boolean If true, events should not be triggered as a result of this set.
                    Returns:
                    this, chainable. {Coral.Component}
                    Inherited From:

                    instance.show

                    Show this component.
                    Returns:
                    this, chainable {Coral.Component}
                    Inherited From:

                    instance.trigger

                    Trigger an event.
                    Parameters:
                    Name Type Optional Default Description
                    eventName String No
                    		 The event name to trigger.
                    props Object Yes
                    		 Additional properties to make available to handlers as event.detail.
                    bubbles Boolean Yes
                    		 Set to false to prevent the event from bubbling.
                    cancelable Boolean Yes
                    		 Set to false to prevent the event from being cancelable.
                    Returns:
                    CustomEvent object {CustomEvent}
                    Inherited From:

                    Events

                    coral-component:attached

                    Triggered when the component is attached to the DOM.
                    Callback Parameters:
                    Name Type Description
                    event Object Event object.
                    Inherited From:
                    Deprecated:
                    • since 1.14.0, use MutationObserver instead.

                      coral-component:detached

                      Triggered when the component is detached to the DOM.
                      Callback Parameters:
                      Name Type Description
                      event Object Event object.
                      Inherited From:
                      Deprecated:
                      • since 1.14.0, use MutationObserver instead.

                        coral-component:ready

                        Triggerred when the component has been upgraded and is ready for use.
                        Callback Parameters:
                        Name Type Description
                        event Object Event object.
                        Inherited From:
                        Deprecated:
                        • since 1.9.0, use Coral.commons.ready() instead.