Modal Components

Modals are opened using a “last in first out” stack. If multiple modals are opened, the top modal receives an isActive prop of true and the rest receive false. Use this in your modal component to conditionally render or display the modal.

When a modal is closed it is unmounted and removed from the stack.

MyModal.svelte

<script>
  const { isActive } = $props()
</script>

{#if isActive}
  <div>
    <!-- ... -->
  </div>
{/if}

<!-- or if you need to preserve state of child components -->
<div class:hidden={!isActive} aria-hidden={!isActive}>
  <!-- ... -->
</div>

<style>
  .hidden {
    display: none;
  }
</style>

Opening Modals

Modals are opened with modals.open(YourModalComponent, props).

<script>
  import { modals } from 'svelte-modals'
  import ConfirmModal from '../components/ConfirmModal.svelte'
  import AlertModal from '../components/AlertModal.svelte'

  async function show() {
    const result = await modals.open(ConfirmModal, {
      message: 'Are you sure?'
    })

    if (result === 'confirm') {
      modals.open(AlertModal, { message: 'You confirmed' })
    } else {
      modals.open(AlertModal, { message: 'You cancelled' })
    }
  }
</script>

<button onclick={show}>Open</button>

Open

Note

modals.open returns a promise that resolves when the modal is closed. Modals can return a value if they close using their close() prop.

Multiple Modals

If another modal is opened while a modal is already open, the current modal will be hidden (by receiving an isActive prop of false) and the new modal will be shown.

<script>
  import { modals} from 'svelte-modals'
  import ConfirmModal from '../components/ConfirmModal.svelte'

  function openInfiniteModal() {
    modals.open(ConfirmModal, {
      message: 'Open another modal? This is modal #' + (modals.stack.length + 1),
      onconfirm: () => openInfiniteModal()
    })
  }
</script>

<button onclick={openInfiniteModal}>Open</button>

Open

Closing Modals

From anywhere in your app you can call modals.close() to close the top modal, modals.close(amount) to close a given number of modals, or modals.closeAll() to close all modals.

<script>
  import { modals } from 'svelte-modals'

  // close 1 modal
  modals.close()

  // close 2 modals
  modals.close(2)

  // close all modals
  modals.closeAll()
</script>

Note

When closing modals this way, any corresponding modals.open will resolve with undefined. If you need to return a value, you should use the close() prop

The close() Prop

Modals receive a close prop which will close the modal and resolve the corresponding modals.open with the given value.

ConfirmModal.svelte

<script>
  const { isActive, close } = $props()
</script>

{#if isActive}
  <div>
    <!-- ... -->
    <button onclick={() => close('cancel')}>Cancel</button>
    <button onclick={() => close('confirm')}>Confirm</button>
  </div>
{/if}

<script>
  import { modals } from 'svelte-modals'
  import ConfirmModal from '../components/ConfirmModal.svelte'
  import AlertModal from '../components/AlertModal.svelte'

  async function show() {
    const result = await modals.open(ConfirmModal, { message: 'Are you sure?' })

    modals.open(AlertModal, { message: 'You chose: ' + result })
  }
</script>

<button onclick={show}>Open</button>

Open

If you are using Typescript, you can define the type of the value by using the ModalProps interface.

ConfirmModal.svelte

<script lang="ts">
  import type { ModalProps } from 'svelte-modals'

  type Result = 'cancel' | 'confirm'

  const { isActive, close }: ModalProps<Result> = $props()
</script>

{#if isActive}
  <div>
    <!-- ... -->
    <button onclick={() => close('cancel')}>Cancel</button>
    <button onclick={() => close('confirm')}>Confirm</button>
  </div>
{/if}

const result = await modals.open(ConfirmModal, { message: 'Are you sure?' })

result // 'cancel' | 'confirm'

Transitions

Transitions can be added to your modal components just like any other Svelte component. They must be global transitions because they are mounted and unmounted by the <ModalStack /> component.

MyModal.svelte

<script>
  import { fade } from 'svelte/transition'

  const { isActive, close, title, message } = $props()
</script>

{#if isActive}
  <div
    role="dialog"
    class="modal-container"
    transition:fade|global
  >
    <div class="modal-content">
      <h2>{title}</h2>
      <p>{message}</p>

      <div class="modal-actions">
        <button onclick={() => close()}>OK</button>
      </div>
    </div>
  </div>
{/if}

Open Modal

Transitions between Modals

By default, when opening one modal after another the transitions for both will play at the same time. Depending on your animation this might be ok, but often it’s cleaner to transition one at a time.

To control this behaviour, you can forward on the onintrostart and onoutroend props to your modal. This tells <ModalStack /> to wait for the transition to finish before opening the next modal.

MyModal.svelte

<script>
  import { fade } from 'svelte/transition'

  const { isActive, onintrostart, onoutroend } = $props()
</script>

{#if isActive}
  <div
    role="dialog"
    transition:fade|global
    {onintrostart}
    {onoutroend}
  >
    <!-- ... -->
  </div>
{/if}

With forwarding Without forwarding

Lazy Loading

Modal components can be lazy loaded with dynamic imports

import { modals } from 'svelte-modals'

modals.open(() => import('./AlertModal.svelte'), {
  title: 'Lazy Modal',
  message: 'This modal was loaded lazily'
})

Open Modal

While the component is being imported, the <ModalStack /> component will render backdrop and loading snippets.

Snippets

Snippets can be passed in as props the same way you would with a regular Svelte 5 component.

SnippetModal.svelte

<script>
  const { isActive, close, content } = $props()
</script>

{#if isActive}
  <div>
    <!-- ... -->
    {@render content()}
  </div>
{/if}

<script>
  import { modals } from 'svelte-modals'
  import SnippetModal from '../components/SnippetModal.svelte'

  function onclick() {
    modals.open(SnippetModal, {
      content
    })
  }
</script>

{#snippet content()}
  <div>Snippet content</div>
{/snippet}

<button onclick={onclick}>Open Modal</button>

Open Modal

Props

Modal components receive the following props:

interface ModalProps<ReturnValue = any> extends Record<string, any> {
  // whether the modal is currently open
  isActive: boolean

  // the unique id of the modal
  id: string

  // the index of the modal in the stack
  index: number

  // closes the modal with an optional return value
  close: (value?: ReturnValue) => void

  // for transitions, see Transitions section
  onintrostart: () => void
  onoutroend: () => void
}

If you’re using Typescript, you should use this interface to define the props of your modal components.

MyModal.svelte

<script lang="ts">
  import type { ModalProps } from 'svelte-modals'

  // optional
  type CloseValue = 'cancel' | 'confirm'

  interface MyModalProps extends ModalProps<CloseValue> {
    title: string
  }

  const { isActive, title, close }: MyModalProps = $props()

  function handleConfirm() {
    // uses CloseValue
    close('confirm')
  }
</script>