The modal component can be used as an interactive dialog on top of the main content area of the website to show notifications and gather information using form elements from your website users.
Setup
<script>
import { Modal } from '.';
</script> Default modal
Modal visibility (open/close) is controlled by the open property. You can bind it to a variable that other element (usually button) will toggle.
Upon action taken from user i.e. pressing the action button, the onaction callback function will be called.
Modal can me dismissed (canceled) by pressing Esc key, clicking outside of it or clicking the close button.
<script>
import { Button, Modal } from '.';
let defaultModal = $state(false);
</script>
<Button onclick={() => (defaultModal = true)}>Default modal</Button>
<Modal
title="Terms of Service"
form
bind:open={defaultModal}
onaction={({ action }) => alert(`Handle "${action}"`)}
>
<p>
With less than a month to go before the European Union enacts new consumer privacy laws for its
citizens, companies around the world are updating their terms of service agreements to comply.
</p>
<p>
The European Union’s General Data Protection Regulation (G.D.P.R.) goes into effect on May 25
and is meant to ensure a common set of data rights in the European Union. It requires
organizations to notify users as soon as possible of high-risk data breaches that could
personally affect them.
</p>
{#snippet footer()}
<Button type="submit" value="success">I accept</Button>
<Button type="submit" value="decline" color="alternative">Decline</Button>
{/snippet}
</Modal> This component is built upon the dialog - form pair (note the form property set on dialog above):
<dialog>
<form method="dialog">...</form>
</dialog> In such a structure, it is enough to press <button type="submit" value="somevalue"> to close the dialog and sets its return value to the value parameter of that submitter. Use a convenience callback onaction to get the action info:
function onaction(params: {
action: string; // name of the action
data: FormData; // form data - if other then buttons form elements used
}): void; Returning explicit false from onaction prevents the dialog from closing. See Form element
Note: Bitblue <Button> by default is implemented as <button type="button">, so to use it as an action button you have to explicity change its type: <Button type="submit">. Leaving value parameter empty, will cancel the dialog without triggering onaction.
Pop-up modal
You can use this modal example to show a pop-up decision dialog to your users especially when deleting an item and making sure if the user really wants to do that by double confirming.
Notice the permanent prop causing that user is forced to take an action, as all canceling functions will be disabled (Esc key, click outside, close button).
Notice as well the lack of the footer snippet and the transition set to slide.
<script>
import { Button, Modal } from '.';
import { slide } from 'svelte/transition';
let popupModal = $state(false);
</script>
<Button onclick={() => (popupModal = true)}>Pop-up modal</Button>
<Modal form bind:open={popupModal} size="xs" transition={slide} permanent>
<div class="text-center">
<iconify-icon
style="font-size: 20px;"
icon="mynaui:danger-circle-solid"
class="mx-auto mb-4 text-gray-400 dark:text-gray-200"
></iconify-icon>
<h3 class="mb-5 text-lg font-normal text-gray-500 dark:text-gray-400">
Are you sure you want to delete this product?
</h3>
<div class="space-x-2">
<Button type="submit" value="yes" color="red">Yes, I'm sure</Button>
<Button type="submit" value="no" color="alternative">No, cancel</Button>
</div>
</div>
</Modal> Form element
Use this modal example with form input element to receive information from your users with the advantage of not having to link to another page but keeping the user on the currently active page. A great example would be a login or a register form.
<script>
import { Button, Modal, Input, Label } from '.';
let formModal = $state(false);
let error = $state('');
function onaction({ action, data }) {
error = '';
// Check the data validity, return false to prevent dialog closing; anything else to proceed
if (action == 'login' && data.get('password').length < 4) {
error = 'Password must have at least 4 characters';
return false;
}
}
</script>
<Button onclick={() => (formModal = true)}>Form modal</Button>
<Modal form bind:open={formModal} size="xs" {onaction}>
<div class="flex flex-col space-y-6">
<h3 class="mb-4 text-xl font-medium text-gray-900 dark:text-white">Sign in to our platform</h3>
{#if error}
<label color="red">{error}</label>
{/if}
<Label class="space-y-2">
<span>Email</span>
<Input type="email" name="email" placeholder="name@company.com" required />
</Label>
<Label class="space-y-2">
<span>Your password</span>
<Input type="password" name="password" placeholder="min. 4 characters" required />
</Label>
<Button type="submit" value="login">Login to your account</Button>
</div>
</Modal> Clicking outside
Modal has got the prop outsideclose set to true by default, to allow the user to close the modal by clicking outside of it. If you want to block that behaviour set that prop to false.
You can control that outside space - called backdrop - by passing the backdrop: Tailwind class.
This example shows the header customization as well.
<script>
import { Button, Modal } from '.';
let open = $state(false);
</script>
<Button onclick={() => (open = true)}>Default modal</Button>
<Modal
form
bind:open
outsideclose={false}
class="backdrop:bg-red-900/50 dark:backdrop:bg-green-300/50"
>
{#snippet header()}
<h3>
Terms of Service <small class="font-normal">(Revised)</small>
</h3>
{/snippet}
<p>
With less than a month to go before the European Union enacts new consumer privacy laws for its
citizens, companies around the world are updating their terms of service agreements to comply.
</p>
<p>
The European Union’s General Data Protection Regulation (G.D.P.R.) goes into effect on May 25
and is meant to ensure a common set of data rights in the European Union. It requires
organizations to notify users as soon as possible of high-risk data breaches that could
personally affect them.
</p>
{#snippet footer()}
<Button type="submit" value="accept">I accept</Button>
<Button type="submit" color="alternative">Decline</Button>
{/snippet}
</Modal> An option of automatic closing of the modal can be enabled by setting the autoclose property. Any <button> element put in the modal will close it on click.
Sizes
You can use five different modal sizing options starting from extra small to extra large, but keep in mind that the width of these modals will remain the same when browsing on smaller devices.
<script lang="ts">
import { Button, Modal, type ModalProps } from '.';
let openModal = $state(false);
let size: ModalProps['size'] = $state('md'); // Set default value
function onclick(modalSize: ModalProps['size']) {
size = modalSize;
openModal = true;
}
</script>
<div class="block space-y-4 md:space-y-0 md:space-x-4 rtl:space-x-reverse">
<Button onclick={() => onclick('xs')}>xs</Button>
<Button onclick={() => onclick('sm')}>sm</Button>
<Button onclick={() => onclick('md')}>md</Button>
<Button onclick={() => onclick('lg')}>lg</Button>
<Button onclick={() => onclick('xl')}>xl</Button>
</div>
<Modal form title="Terms of Service" bind:open={openModal} {size}>
<p>
With less than a month to go before the European Union enacts new consumer privacy laws for its
citizens, companies around the world are updating their terms of service agreements to comply.
</p>
<p>
The European Union’s General Data Protection Regulation (G.D.P.R.) goes into effect on May 25
and is meant to ensure a common set of data rights in the European Union. It requires
organizations to notify users as soon as possible of high-risk data breaches that could
personally affect them.
</p>
{#snippet footer()}
<Button type="submit">I accept</Button>
<Button type="submit" color="alternative">Decline</Button>
{/snippet}
</Modal> Placement
<script lang="ts">
import { Button, Modal } from '.';
type ModalPlacementType =
| 'top-left'
| 'top-center'
| 'top-right'
| 'center-left'
| 'center'
| 'center-right'
| 'bottom-left'
| 'bottom-center'
| 'bottom-right';
let placement: ModalPlacementType = $state('center');
let openPlacement = $state(false);
const setPlacement = (newPlacement: ModalPlacementType) => {
placement = newPlacement;
console.log('placement: ', placement);
openPlacement = !openPlacement;
};
</script>
<div class="inline-grid grid-cols-3 grid-rows-3 gap-4">
<Button onclick={() => setPlacement('top-left')}>top-left</Button>
<Button onclick={() => setPlacement('top-center')}>top-center</Button>
<Button onclick={() => setPlacement('top-right')}>top-right</Button>
<Button onclick={() => setPlacement('center-left')}>center-left</Button>
<Button onclick={() => setPlacement('center')}>center</Button>
<Button onclick={() => setPlacement('center-right')}>center-right</Button>
<Button onclick={() => setPlacement('bottom-left')}>bottom-left</Button>
<Button onclick={() => setPlacement('bottom-center')}>bottom-center</Button>
<Button onclick={() => setPlacement('bottom-right')}>bottom-right</Button>
</div>
<Modal title="Terms of Service" form bind:open={openPlacement} {placement}>
<p
>With less than a month to go before the European Union enacts new consumer privacy laws for its
citizens, companies around the world are updating their terms of service agreements to comply.</p
>
<p
>The European Union’s General Data Protection Regulation (G.D.P.R.) goes into effect on May 25
and is meant to ensure a common set of data rights in the European Union. It requires
organizations to notify users as soon as possible of high-risk data breaches that could
personally affect them.</p
>
{#snippet footer()}
<Button type="submit">I accept</Button>
<Button type="submit" color="alternative">Decline</Button>
{/snippet}
</Modal> Modal events
Modal triggers the close or cancel events - see <dialog> API for details.
The oncancel handler will run when dialog is closed by non-action trigger: Esc key, click outside, close button, submit button with empty value attribute. This event is cancelable.
Use the onclose event handler to run code when the modal closes, regardless of how it was triggered.
You can as well use the onsubmit event handler which is bubbled event from the internal form.
<script lang="ts">
import { Button, Modal } from '.';
let open = $state(false);
</script>
<Button onclick={() => (open = true)}>Default modal</Button>
<Modal
form
bind:open
onsubmit={(ev) => alert(`SUBMIT: Form is about to be submitted.`)}
oncancel={(ev) => alert('CANCEL: User canceled the dialog')}
onclose={(ev) =>
alert(
`CLOSE: Dialog closed with "${(ev.target as HTMLDialogElement)?.returnValue || 'no'}" action.`
)}
title="Terms of Service"
>
<p
>With less than a month to go before the European Union enacts new consumer privacy laws for its
citizens, companies around the world are updating their terms of service agreements to comply.</p
>
<p
>The European Union's General Data Protection Regulation (G.D.P.R.) goes into effect on May 25
and is meant to ensure a common set of data rights in the European Union. It requires
organizations to notify users as soon as possible of high-risk data breaches that could
personally affect them.</p
>
{#snippet footer()}
<Button type="submit" value="accept">I accept</Button>
<Button type="submit" value="decline" color="alternative">Decline</Button>
{/snippet}
</Modal> Accessibility
Modal now uses the native <dialog> element (native dialog pattern):
showModal()for modal dialogs (backdrop + inert page)- Focus moves into the dialog on open; restored on close
focustrapdefaults totrue(Tab cycles within the dialog)- Escape / backdrop click fire a cancelable
cancelevent (oncancel); permanent dialogs ignore dismiss aria-modal="true"andaria-labelledbywhentitleis set- Prefer
data-autofocuson the field that should receive initial focus
<script lang="ts">
import { Button, Modal, Input, Label } from '.';
let open = $state(false);
</script>
<Button onclick={() => (open = true)}>Open</Button>
<Modal bind:open title="Accessible form" form>
<Label class="mb-2" for="email">Email</Label>
<Input id="email" data-autofocus type="email" name="email" />
{#snippet footer()}
<Button type="submit" value="save">Save</Button>
{/snippet}
</Modal> Props
ModalProps
| Prop | Type | Default | Description |
|---|---|---|---|
open | boolean | false | Bindable visibility |
title | string | — | Header title + aria-labelledby |
header | Snippet | — | Custom header (when no title) |
footer | Snippet | — | Footer actions region |
children | Snippet | — | Dialog body |
form | boolean | false | Wrap body in <form method="dialog"> |
modal | boolean | true | showModal() vs show() |
focustrap | boolean | true | Trap Tab inside dialog |
dismissable | boolean | true | Show close button |
permanent | boolean | false | Block Esc / backdrop dismiss |
outsideclose | boolean | true | Backdrop click cancels |
autoclose | boolean | false | Any button click closes |
fullscreen | boolean | false | Full-viewport dialog |
size | none | xs | sm | md | lg | xl | md | Max width |
placement | top-left | top-center | top-right | center-left | center | center-right | bottom-left | bottom-center | bottom-right | center | Margin-based placement |
transition | TransitionFunc | fade | Enter/exit transition |
params | ParamsType | { duration: 100, easing: sineIn } | Transition params |
onaction | ({ action, data }) => false? | — | Form action; return false to keep open |
headerClass | ClassValue | — | Header classes (prefer classes.header) |
bodyClass | ClassValue | — | Body classes |
footerClass | ClassValue | — | Footer classes |
closeBtnClass | ClassValue | — | Close button classes |
classes | slot class map | — | Theme slot overrides |
class | ClassValue | — | Root dialog classes |
…rest | HTMLDialogAttributes | — | Forwarded to <dialog> |
Snippets
| Snippet | Description |
|---|---|
children | Dialog body |
header | Custom header content |
footer | Footer actions (submit buttons, etc.) |
Events
| Event / callback | Description |
|---|---|
onaction | Dialog form action with { action, data: FormData } |
oncancel | Cancelable dismiss (Esc / backdrop) |
onclose | After close |
ontoggle | Native dialog toggle |
onsubmit | Native form submit |