Modal Components

Modals are opened using a “last in first out” stack. Each time a modal is opened it gets added to the top of the stack. When closed it unmounts and is removed, revealing the next modal in the stack (if there is one).

Each modal component receives an isActive prop to determine if it is the currently shown modal. This should be used by your modal component to conditionally render or display itself.

MyModal.svelte

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

<!-- in most cases you can do this -->
{#if isActive}
  <div>
    <!-- ... -->
  </div>
{/if}

<!--
 but if you prefer you can visually hide your modal instead,
 preserving state of any children components
-->
<div class:hidden={!isActive} aria-hidden={!isActive}>
  <MyForm />
</div>

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

Opening Modals

To open a modal, import modals and call 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.

Stacking Modals

You can call modals.open any time to open a new modal. This will add the new modal to the top of the stack, keeping the previous modals mounted but updating their isActive prop to false.

<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 the last given number of modals, or modals.closeAll() to close all modals.

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

  // close the current modal
  modals.close()

  // close the last 2 modals
  modals.close(2)

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

Note

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

The close() Prop

Modals receive a close prop which will close the modal and resolve their 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. However 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>