ui/docs/content/3.components/modal.md

description, links

description	links
A dialog window that can be used to display a message or request user input.	label icon to Dialog i-custom-radix-vue https://www.radix-vue.com/components/dialog.html label icon to GitHub i-simple-icons-github https://github.com/benjamincanac/ui3/tree/dev/src/runtime/components/Modal.vue

Usage

Use a Button or any other component in the default slot of the Modal.

Then, use the #content slot to add the content displayed when the Modal is open.

::component-code

prettier: true class: 'justify-center' slots: default: |

<UButton label="Open" color="gray" variant="subtle" />

content: |

<Placeholder class="h-48 m-4" />

---

:u-button{label="Open" color="gray" variant="subtle"}

#content :placeholder{class="h-48 m-4"} ::

You can also use the #header{lang="ts-type"}, #body{lang="ts-type"} and #footer{lang="ts-type"} slots to customize the Modal's content.

Title

Use the title prop to set the title of the Modal's header.

::component-code

prettier: true class: 'justify-center' props: title: 'Modal with title' slots: default: |

<UButton label="Open" color="gray" variant="subtle" />

body: |

<Placeholder class="h-48" />

---

:u-button{label="Open" color="gray" variant="subtle"}

#body :placeholder{class="h-48"} ::

Description

Use the description prop to set the description of the Modal's header.

::component-code

prettier: true class: 'justify-center' ignore:

• title props: title: 'Modal with description' description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.' slots: default: |

body: |

<Placeholder class="h-48" />

---

:u-button{label="Open" color="gray" variant="subtle"}

#body :placeholder{class="h-48"} ::

Close

Use the close prop to customize or hide the close button displayed in the Modal's header. You can pass all the props of the Button component to customize it.

::tip The close button is not displayed if the #content slot is used as it's a part of the header. ::

Use the close-icon prop to customize the button Icon. Defaults to i-heroicons-x-mark-20-solid.

::component-code

prettier: true class: 'justify-center' ignore:

• title

• close.color

• close.variant props: title: 'Modal with close button' close: color: primary variant: outline class: 'rounded-full' closeIcon: '' slots: default: |

body: |

<Placeholder class="h-48" />

---

:u-button{label="Open" color="gray" variant="subtle"}

#body :placeholder{class="h-48"} ::

::tip You can customize this icon globally in your app.config.ts under ui.icons.close key. ::

Overlay

Use the overlay prop to control whether the Modal has an overlay or not. Defaults to true.

::component-code

prettier: true ignore:

• title class: 'justify-center' props: overlay: false title: 'Modal fullscreen' slots: default: |

body: |

<Placeholder class="h-48" />

---

:u-button{label="Open" color="gray" variant="subtle"}

#body :placeholder{class="h-48"} ::

Transition

Use the transition prop to control whether the Modal is animated or not. Defaults to true.

::component-code

prettier: true ignore:

• title class: 'justify-center' props: transition: false title: 'Modal fullscreen' slots: default: |

body: |

<Placeholder class="h-48" />

---

:u-button{label="Open" color="gray" variant="subtle"}

#body :placeholder{class="h-48"} ::

Fullscreen

Use the fullscreen prop to make the Modal fullscreen.

::component-code

prettier: true ignore:

• title

• fullscreen class: 'justify-center' props: fullscreen: true title: 'Modal fullscreen' slots: default: |

body: |

<Placeholder class="h-full" />

---

:u-button{label="Open" color="gray" variant="subtle"}

#body :placeholder{class="h-full"} ::

Prevent close

Use the prevent-close prop to prevent the Modal from being closed when clicking outside of it.

::component-code

prettier: true ignore:

• title

• preventClose class: 'justify-center' props: preventClose: true title: 'Modal prevent close' slots: default: |

body: |

<Placeholder class="h-48" />

---

:u-button{label="Open" color="gray" variant="subtle"}

#body :placeholder{class="h-48"} ::

Examples

Control open state

You can control the open state by using the default-open prop or the v-model:open directive.

::component-example

name: 'modal-open-example' class: 'justify-center'

::

::note In this example, press :kbd{value="O"} to toggle the Modal. ::

::tip This allows you to move the trigger outside of the Modal or remove it entirely. ::

Control programatically

You can use the useModal composable to open a Modal programatically.

::important Make sure to wrap your app with the App component that instantiates the ModalProvider component. ::

First, create a modal component that will be opened programatically:

<script lang="ts" setup>
const modal = useModal()

defineProps<{
  count: number
}>()
</script>

<template>
  <UModal :title="`This modal was opened programmatically ${count} times`">
    <template #footer>
      <UButton color="gray" label="Close" @click="modal.close()" />
    </template>
  </UModal>
</template>

Then, use it in your app:

::component-example

name: 'modal-programmatic-example' class: 'justify-center'

::

::tip You can close the modal within the modal component by calling modal.close(). ::

Nested modals

You can nest modals within each other.

::component-example

name: 'modal-nested-example' class: 'justify-center'

::

With footer slot

Use the #footer slot to add content after the Modal's body.

::component-example

name: 'modal-footer-slot-example' class: 'justify-center'

::

With command palette

You can use the CommandPalette component inside the Modal.

::component-example

collapse: true name: 'modal-command-palette-example' class: 'justify-center'

::

API

Props

:component-props

Slots

:component-slots

Emits

:component-emits

Theme

:component-theme