svelte-simple-modal

Live demo: https://svelte.dev/repl/033e824fad0a4e34907666e7196caec4?version=3.20.1

Works with: Svelte >=v3.4 (Tested until to v3.20)

Table of Contents

• Install
  • Rollup Setup
  • Sapper Setup
• Usage
  • SSR
• API
  • Component
  • Events
  • Context API
  • Store API
• FAQ

Install

npm install --save svelte-simple-modal

Rollup Setup

Make sure that the main application's version of svelte is used for bundling by setting rollup-plugin-node-resolve's dedupe option as follows:

import resolve from 'rollup-plugin-node-resolve';

export default {
  plugins: [
    resolve({
      dedupe: ['svelte', 'svelte/transition', 'svelte/internal'], // important!
    }),
  ],
};

Sapper Setup

Make sure you install svelte-simple-modal as a dev-dependency.

npm install -D svelte-simple-modal

Usage

Import the Modal component into your main Svelte component (e.g., App.svelte).

The Modal is exposing two context functions for opening and closing the modal. open() opens a component as a modal and expects two arguments: a Svelte Component and optionally an object literal with the component's props. close() simply closes the modal.

Alternatively, you can show a component as a modal by passing it to the <Modal show={} /> as a Svelte store.

<!-- App.svelte -->
<script>
  import Content from './Content.svelte';
  import Modal from 'svelte-simple-modal';
</script>

<Modal>
  <Content />
</Modal>


<!-- Content.svelte -->
<script>
  import { getContext } from 'svelte';
  import Surprise from './Surprise.svelte';

  const { open } = getContext('simple-modal');

  const showSurprise = () => {
    open(Surprise, { message: "It's a modal!" });
  };
</script>

<p><button on:click={showSurprise}>Show me a surprise!</button></p>


<!-- Surprise.svelte -->
<script>
  export let message;
</script>

<p>
  🎉 {message} 🍾
</p>

Server-Side Rendering

With SvelteKit you can enable SSR using the browser environmental variable as follows:

<script>
  import Modal from 'svelte-simple-modal';
  import { browser } from '$app/env';
</script>

{#if browser}
  <Modal>
    <Content />
  </Modal>
{/if}

Alternatively, you can enable SSR by dynamically importing svelte-simple-modal in onMount() as follows:

import { onMount } from 'svelte';

onMount(async () => {
  const svelteSimpleModal = await import('svelte-simple-modal');
  Modal = svelteSimpleModal.default;
});

API

Component API

The <Modal /> component accepts the following optional properties:

Component Events

The <Modal /> component dispatches the following events:

• open: dispatched when the modal window starts to open.
• opened: dispatched when the modal window opened.
• close: dispatched when the modal window starts to close.
• closed: dispatched when the modal window closed.

Alternatively, you can listen to those events via callbacks passed to open() and close().

Context API

You can access the context via getContext('simple-modal'). It exposes the following two methods:

# open(Component, props = {}, options = {}, callbacks = {})

Opens the modal with <Component {props}> rendered as the content. options can be used to adjust the modal behavior once for the modal that is about to be opened. The options allows to customize all parameters except key and setContext:

{
  closeButton: false,
  closeOnEsc: false,
  closeOnOuterClick: false,
  transitionBg: fade,
  transitionBgProps: {
    duration: 5000
  },
  transitionWindow: fly,
  transitionWindowProps: {
    y: 100,
    duration: 250
  },
  styleBg: { backgroundImage: 'http://example.com/my-background.jpg' },
  styleWindow: { fontSize: '20em' },
  styleContent: { color: 'yellow' },
  styleCloseButton: { width: '3rem', height: '3rem' },
  disableFocusTrap: true
}

# close(callbacks = {})

Closes the modal. Similar to open(), this method supports adding callbacks for the closing transition:

{
  onClose: () => { /* modal window starts to close */ },
  onClosed: () => { /* modal window closed */ },
}

Callbacks are triggered at the beginning and end of the opening and closing transition. The following callbacks are supported:

{
  onOpen: () => { /* modal window starts to open */ },
  onOpened: () => { /* modal window opened */ },
  onClose: () => { /* modal window starts to close */ },
  onClosed: () => { /* modal window closed */ },
}

Store API

You can also use Svelte stores to open a modal using the <Modal />'s show property as follows:

<!-- App.svelte -->
<script>
  import { writable } from 'svelte/store';
  import Content from './Content.svelte';
  import Popup from './Popup.svelte';
  export const modal = writable(null);

  function showModal() {
    modal.set(Popup)
  }
</script>

<Content />
<button on:click={showModal}>Show modal</button>


<!-- Content.svelte -->
<script>
  import Modal from 'svelte-simple-modal';
  import SomethingElse from './SomethingElse.svelte';
  import { modal } from './App.svelte';
</script>

<Modal show={$modal}>
  <SomethingElse />
</Modal>

An added benefit of using stores is that the component opening the modal does not have to be a parent of <Modal />. For instance, in the example above, App.svelte is toggling Popup.svelte as a modal even though App.svelte is not a child of <Modal />.

Bind Props to a Component Shown as a Modal

Sometimes you want to pass properties to the component shown as a modal. To accomplish this, you can use our bind() helper function as follows:

<script>
  import { bind } from 'svelte-simple-modal';
  import Popup from './Popup.svelte';
  import { modal } from './App.svelte';

  modal.set(bind(Popup, { name: 'custom name' }));
</script>

If you've worked with React/JSX then think of const c = bind(Component, props) as the equivalent of const c = <Component ...props />.

FAQ

Custom Close Button

This feature requires Svelte >=v3.19!

Unfortunately, it's not possible to adjust all styles of the built-in close button via the styleCloseButton option. If you need full control you can implement your own Svelte component and use that as the close button. To do so pass your component via the closeButton option to <Modal /> or open().

For example, your close button might look as follows:

<!-- CloseButton.svelte -->
<script>
  // This property is used by Modal.svelte to pass down the close function
  export let onClose;
</script>

<button on:click={onClose}>Custom Close Button</button>

<style>
  /* Customize to your liking */
  button {
    position: absolute;
    top: -3rem;
    right: 0;
  }
</style>

Now you can set it as the default close button by passing it to <Modal /> as follows:

<!-- App.svelte -->
<script>
  import Content from './Content.svelte';
  import CloseButton from './CloseButton.svelte';
  import Modal from 'svelte-simple-modal';
</script>

<Modal closeButton={CloseButton}>
  <Content />
</Modal>

Or you can pass CloseButton to open() as shown below:

<!-- Content.svelte -->
<script>
  import { getContext } from 'svelte';
  import Surprise from './Surprise.svelte';
  import CloseButton from './CloseButton.svelte';

  const { open } = getContext('simple-modal');

  const showSurprise = () => {
    open(Surprise, { message: "It's a modal!" }, { closeButton: CloseButton });
  };
</script>

<p><button on:click={showSurprise}>Show me a surprise!</button></p>

License

MIT