Kongponents

Modal ​

INFO

Are you looking for a modal with a close icon, left-aligned text, right-aligned action buttons, and divider lines at the top and bottom of the modal? Try KPrompt instead.

The KModal component is used for displaying general information to a user that must be acknowledged before continuing.

html
<template>
  <div>
    <KButton appearance="primary" @click="isVisible = true">Open Modal</KButton>

    <KModal
      title="Look Mah!"
      content="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris accumsan tincidunt velit ac vulputate. Aliquam turpis odio, elementum a hendrerit id, pellentesque quis ligula. Nulla ultricies sit amet nisi vitae congue. Quisque vitae ullamcorper leo, id pretium mi. Nam sed odio dapibus, dapibus augue at, pulvinar est."
      :isVisible="isVisible"
      @proceed="isVisible = false"
      @canceled="isVisible = false"
    />
  </div>
</template>

<script lang="ts">
import { defineComponent } from 'vue'

export default defineComponent({
  data () {
    return {
      isVisible: false
    }
  }
})
</script>

Props ​

isVisible ​

Tells the component whether or not to render the open modal.

title ​

Text displayed in header if not using slot (Note: this field is still required for accessibility reasons even if using the slot).

hideTitle ​

If not using the header-content slot, tells the component whether or not to display the title.

content ​

Text to display in content if not using slot.

html
<KModal
  :isVisible="isVisible"
  hide-title
  title="I hid my title"
  content="I am customized!"
  @proceed="isVisible = false"
  @canceled="isVisible = false"
/>

textAlign ​

The alignment for the title and content. Supports left, center (default), or right.

actionButtonText ​

Change the text content of the submit/proceed button.

actionButtonAppearance ​

Change the appearance of the submit/proceed button.

cancelButtonText ​

Change the text content of the close/cancel button.

cancelButtonAppearance ​

Change the appearance of the cancel button.

html
<KModal
  :isVisible="isVisible"
  title="Look Mah!"
  content="I am customized!"
  actionButtonText="Go"
  actionButtonAppearance="creation"
  cancelButtonText="Abort"
  cancelButtonAppearance="danger"
  @proceed="isVisible = false"
  @canceled="isVisible = false"
/>

hideCancelButton ​

Use this to hide the built-in cancel button (false by default).

hideDismissIcon ​

When using the header-image slot we display a dismiss 'X' button in the upper right corner of the dialog. Set this prop to true to hide the button (false by default).

TIP

If you want to have a dismiss icon on your dialog without using the header-image slot, you should use the KPrompt component.

dismissButtonTheme ​

Can be dark (default) or light. You might want to use this if displaying dark content in the header-image slot.

html
<KModal
  :is-visible="isVisible"
  title="Welcome!"
  hide-cancel-button
  text-align="left"
  dismiss-button-theme="light"
  @canceled="isVisible = false"
>
  <template v-slot:header-image>
    <div class="slot-image-content1">
      <img src="/img/dark-demo.png" alt="Circuit board" />
    </div>
  </template>
  <template v-slot:header-content>
    <KIcon icon="kong" />
    Welcome!
  </template>
  <template v-slot:body-content>Get set up with the quickstart to see live data pushed through a gateway service within minutes.</template>
  <template v-slot:action-buttons>
    <KButton appearance="btn-link" @click="isVisible = false">Skip</KButton>
    <KButton
      appearance="primary"
      @click="() => isVisible = false">Onboard me!</KButton>
  </template>
</KModal>

tabbableOptions ​

Options to be passed to focus-trap, which is responsible for trapping focus inside the modal box. If you're experiencing issues with testing <KModal> in jsdom, you can pass this prop according to the focus-trap documentation.

Slots ​

There are 4 designated slots you can use to display content in the modal.

  • header-image - content displayed above the header, ignores padding
  • header-content
  • body-content
  • footer-content - Contains cancel & action buttons by default.
  • action-buttons - Contains action buttons which are right-aligned. This slot will not exist if using footer-content slot.
html
<template>
  <KModal
    :is-visible="slottedIsOpen3"
    title="Look at my slots!"
    content="You know you like these slots."
    dismiss-button-theme="dark"
    @canceled="slottedIsOpen3 = false"
  >
    <template v-slot:header-image>
      <div class="slot-image-content">
        <h4>I'm slotted baby!</h4>
      </div>
    </template>
    <template v-slot:action-buttons>
      <KButton appearance="btn-link" @click="slottedIsOpen3 = false">Pass</KButton>
      <KButton appearance="primary" @click="slottedIsOpen3 = false">I sure do!</KButton>
    </template>
  </KModal>
</template>

<style>
.slot-image-content {
  height: 260px;
  width: 650px;
  background-color: blueviolet;
}
</style>

Events ​

EventDescription
cancelledEmitted when cancel/close button is clicked

Usage ​

Using both the provided props and slot options we will now demonstrate putting it all together. Notice that even though we are using the header-content slot we still specify the title attribute for accessibility.

html
<KModal
  :isVisible="isVisible"
  actionButtonText="Delete"
  actionButtonAppearance="danger"
  @canceled="slottedIsOpen = false"
  title="Delete Item"
>
  <template v-slot:header-content>
    <KIcon icon="dangerCircle" color="red" />
    Delete Item
  </template>
  <template v-slot:body-content>Are you sure you want to delete this item? This action can not be undone.</template>
  <template v-slot:action-buttons>
    <KButton appearance="outline" @click="slottedIsOpen = false">Back</KButton>
    <KButton appearance="danger" @click="slottedIsOpen = false">Delete</KButton>
  </template>
</KModal>

Theming ​

VariablePurpose
--KModalBackdropBackgdrop color
--KModalMaxWidthModal max width
--KModalBorderModal border
--KModalHeaderColorHeader text color
--KModalHeaderSizeHeader font size
--KModalHeaderWeightHeader font weight
--KModalColorMain content text color
--KModalFontSizeMain content text size

An Example of changing the the colors of KModal might look like.

Note: We are scoping the overrides to a wrapper in this example

html
<template>
  <div class="modal-wrapper">
    <KModal
      class="modal-wrapper"
      title="Look Mah!"
      content="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris accumsan tincidunt velit ac vulputate. Aliquam turpis odio, elementum a hendrerit id, pellentesque quis ligula."
      :isVisible="isVisible"
      @canceled="isVisible = false" />
  </div>
</template>

<style>
.modal-wrapper {
  --KModalHeaderColor: red;
  --KModalColor: blue;
  --KModalBackdrop: rgba(94, 174, 255, .25);
}
</style>

Released under the Apache-2.0 License.

Copyright © 2019-present Kong, Inc.