Svelte Modal

Install

pnpm i @isoftdata/svelte-modal

Breaking changes

2.0.0

• Require Svelte 5
• Slots -> Snippets
• Events -> Callbacks
  • Remove backdrop event/callback
  • close callback arg is now a MouseEvent or a KeyboardEvent, and is now also fired when the modal is triggered by pressing "Escape"
• Use $props.id() (uniqueId below) in the default value of "id" related props
  • Default modalId value is now modal-body-${uniqueId} rather than itModal
  • Default closeId value is now close-modal-${uniqueId} rather than close-modal
• Remove m-0 from the div around the footer snippet, which was previous the modalFooter slot.
• Deprecate props with "modal" in name, replace with props with less-redundant names:
  • modalBodyClass -> bodyClass
  • modalDialogClass -> dialogClass
  • modalId -> id
  • modalSize -> size
  • modalHeader -> header
  • modalFooter -> footer

Props

| Name | Type | Description | Default Value | | ---- | ---- | ---------- | ---- | | backdropClickCancels | boolean | Determines whether clicking on the backdrop should close the modal. | true | | bodyClass | ClassValue | Additional CSS classes to apply to the modal body element. | '' | | cancelButtonColor | ButtonColors | The Bootstrap class to apply to the cancel button. | "secondary" | | cancelButtonIcon | IconName \| IconProps | The FontAwesome icon to display on the cancel button, without the preceeding fa-. | "times" | | cancelButtonOutline | boolean | Whether the button should be outlined, instead of solid. | false | | cancelButtonText | string | The text to display on the cancel button. | "Close" | | cancelButtonTitle | string | The title of the cancel button | "" | | cancelShown | boolean | Determines whether the cancel button is shown in the modal (This is the Cancel button at the bottom)footer. | true | | cancelButton | HTMLButtonElement | A reference to the cancel HTMLButtonElement. | undefined (bindable) | | closeId | string | The ID of the close button. | "close-modal" | | closeShown | boolean | Determines whether the close button is shown in the modal (This is the X in the top right corner) header. | true | | confirmButtonColor | ButtonColors | The Bootstrap color class to apply to the confirm button. | "success" | | confirmButtonDisabled | boolean | Determines whether the confirm button is disabled. | false | | confirmButtonIcon | IconName \| IconProps | The FontAwesome icon to display on the confirm button, without the preceeding fa-. | "check" | | confirmButtonIsLoading | boolean | Whether to disable and show a spinner on the "Confirm" button. | false | | confirmButtonOutline | boolean | Whether the button should be outlined, instead of solid. | false | | confirmButtonText | string | The text to display on the confirm button. | "Confirm" | | confirmButtonTitle | string | The title of the confirm button | "" | | confirmDropdownItems | Snippet | A snippet that, if passed, turns the confirm Button into a Dropdown. The contents of this snippet will be applied to the dropdownItems slot of that dropdown | undefined | | confirmShown | boolean | Determines whether the confirm button is shown in the modal footer. | true | | confirmButton | HTMLButtonElement | A reference to the confirm HTMLButtonElement. | undefined (bindable) | | dialogClass | ClassValue | Additional CSS classes to apply to the modal dialog element. | '' | | footerClass | ClassValue | Custom CSS class to apply to the modal footer element. | "align-items-end" | | footerShown | boolean | Determines whether the modal footer is shown. | true | | footerStyle | string | Any additional CSS styles to add to the modal footer. | "" | | form | boolean | Whether to wrap the modal body content in a <form> element. See the Making the confirm button submit the form section below. | false | | formProps | Omit<HTMLFormAttributes, 'onsubmit'> | Additional attributes to add to the <form> element when the form prop is set to true. For onsubmit, use the confirm callback instead. | {} | | fullscreen | boolean \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'xxl' | Breakpoint to apply fullscreen from that size and down. Boolean true for all sizes. This option is only available with Bootstrap 5. | false | | headerShown | boolean | Determines whether the modal header is shown. | true | | id | string | The ID of the modal-body element. | "itModal" | | savingInProgress | boolean | Whether to disable the confirm/cancel buttons and show "Saving..." on the confirm button. | false | | setFocusInModal | boolean | Determines whether to set focus to the modal when it is opened, and restore focus to the previously focused element when it is closed. Learn more in Handling Element Focus. | true | | show | boolean | Determines whether the modal is currently visible or hidden. You probably want to bind: to this. | false (bindable) | | showModalContent | boolean | Determines whether to show the modal content (header, body, and footer) or hide it (can be used for a loading state). | true | | size | "sm" \| "" \| "lg" \| "xl" \| "xxl" | Determines the maximum width of the modal. | "" | | subtitle | string | An optional subtitle to display below the main title. | '' | | title | string | The main title of the modal. | "Confirm" | | transitionMode | string | The transition mode for the modal and its content (possible values: "present", "cardMovePrevious", "cardMoveNext"). | "present" | | zIndex | number | The z-index of the modal element. | 20000 |

Snippets

• default - The modal body.
• header - The modal header.
• footer - the modal footer.

Callbacks

• close(event: MouseEvent | KeyboardEvent) => void - Called when the modal is closed, either through clicking on the backdrop, clicking a close button, or pressing "Escape"
• confirm(event: MouseEvent | SubmitEvent) => void - Called when Confirm button is clicked.

Methods

• prompt() => Promise<boolean> - Opens the modal and returns a promise that resolves once the user has completed their work in the modal. Return is true if the confirm button is clicked, or false if the modal is closed.

Example

<script lang="ts">
	import Modal from '@isoftdata/svelte-modal'
</script>

<Modal
	bind:show
	confirm={() => show = false}
>
	Modal content goes here.
</Modal>

Making the confirm button submit the form

A common need is for the modal-body to contain form elements that are in a <form> element. When the user presses the modal's confirm button, you want it to be the same as submitting the form. To do this, set the form prop to true.

Applying the form prop will ensure the following happen automatically:

• Everything in the default children snippet goes inside a <form> element.
• The confirm button's type is submit and will submit the form when clicked.
• preventDefault will be called on the form's SubmitEvent, so the page doesn't reload.

<script lang="ts">
	import Modal from '@isoftdata/svelte-modal'
</script>

<Modal
	form
	bind:show
	confirm={() => {
		// This will get called when the form is submitted, either by clicking the confirm button or pressing Enter in a form field.
		show = false
	}}
>
	<!-- Everything in this modal body will be in a form element since the form prop is set -->
	<Input bind:value={name} label="Name" />
</Modal>

Handling Element Focus

By default, when the modal is shown, it will attempt to set focus to the .modal-body element if the active element is not already within the .modal-body. When the modal is closed, it will attempt to restore focus to the element that was focused before the modal was opened.

This behavior can be disabled with the setFocusInModal prop(default true). If setFocusInModal is set to false, the modal will not change the focus when it is opened or closed.

You may want to set setFocusInModal to false if you are managing focus manually or if the automatic focus behavior is causing issues in your application. For example, you open Modal B after closing Modal A, and Modal A restores focus back to the previous element in the app, stealing focus away from Modal B.