28 |
29 | **Live demo:** https://svelte.dev/playground/b95ce66b0ef34064a34afc5c0249f313?version=5.17.3
30 |
31 | **Works with:** Svelte `>=v5`!
32 |
33 | > [!NOTE]
34 | > If you want to use Svelte Simple Modal with Svelte v3 or v4, check out [version 1](https://github.com/flekschas/svelte-simple-modal/tree/v1).
35 |
36 | ## Table of Contents
37 |
38 | - [Install](#install)
39 | - [Rollup Setup](#rollup-setup)
40 | - [Usage](#usage)
41 | - [TypeScript Example](#usage-with-typescript)
42 | - [Svelte Store Example](#usage-with-a-svelte-store)
43 | - [Styling](#styling)
44 | - [SSR](#server-side-rendering)
45 | - [Accessibility](#accessibility)
46 | - [API](#api)
47 | - [Component](#component-api)
48 | - [Events](#component-events)
49 | - [Context API](#context-api)
50 | - [Store API](#store-api)
51 | - [FAQ](#faq)
52 |
53 | ## Install
54 |
55 | ```bash
56 | npm install --save svelte-simple-modal
57 | ```
58 |
59 | #### Rollup Setup
60 |
61 | 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:
62 |
63 | ```js
64 | import resolve from '@rollup/plugin-node-resolve';
65 |
66 | export default {
67 | plugins: [
68 | resolve({
69 | dedupe: ['svelte', 'svelte/transition', 'svelte/internal'], // important!
70 | }),
71 | ],
72 | };
73 | ```
74 |
75 | ## Usage
76 |
77 | Import the `Modal` component into your main app component (e.g., `App.svelte`).
78 |
79 | The modal is exposing [two context functions](#context-api):
80 |
81 | - [`open()`](#open) opens a component as a modal.
82 | - [`close()`](#close) simply closes the modal.
83 |
84 | ```svelte
85 |
86 |
90 |
91 |
92 |
93 |
94 |
95 |
101 |
102 |
103 |
104 |
105 |
106 |
109 |
110 |
🎉 {message} 🍾
111 | ```
112 |
113 | **Demo:** https://svelte.dev/repl/52e0ade6d42546d8892faf8528c70d30
114 |
115 | ### Usage with TypeScript
116 |
117 | You can use the `Context` type exported by the package to validate the `getContext` function:
118 |
119 | ```ts
120 | import type { Context } from 'svelte-simple-modal';
121 | const { open } = getContext('simple-modal');
122 | // ...
123 | ```
124 |
125 | ### Usage With a Svelte Store
126 |
127 | Alternatively, you can use a [Svelte store](#store-api) to show/hide a component as a modal.
128 |
129 | ```svelte
130 |
131 |
138 |
139 |
140 |
141 |
142 | ```
143 |
144 | **Demo:** https://svelte.dev/repl/aec0c7d9f5084e7daa64f6d0c8ef0209
145 |
146 | The `` component is the same as in the example above.
147 |
148 | To hide the modal programmatically, simply unset the store. E.g., `modal.set(null)`.
149 |
150 | ### Styling
151 |
152 | The modal comes pre-styled for convenience but you can easily extent or replace the styling using either custom CSS classes or explicit CSS styles.
153 |
154 | Custom CSS classes can be applied via the `classBg`, `classWindow`, `classWindowWrap`, `classContent`, and `classCloseButton` properties. For instance, you could customize the styling with [TailwindCSS](https://tailwindcss.com/) as follows:
155 |
156 | ```svelte
157 |
166 |
167 |
168 | ```
169 |
170 | **Demo:** https://svelte.dev/repl/f2a988ddbd5644f18d7cd4a4a8277993
171 |
172 | > Note: to take full control over the modal styles with CSS classes you have to reset existing styles via `unstyled={true}` as internal CSS classes are always applied last due to Svelte's class scoping.
173 |
174 | Alternatively, you can also apply CSS styles directly via the `styleBg`, `styleWindow`, `styleWindowWrap`, `styleContent`, and `styleCloseButton` properties. For instance:
175 |
176 | ```svelte
177 |
182 |
183 |
184 | ```
185 |
186 | **Demo:** https://svelte.dev/repl/50df1c694b3243c1bd524b27f86eec51
187 |
188 | ### Server-Side Rendering
189 |
190 | With [SvelteKit](https://kit.svelte.dev/) you can enable [SSR](https://www.google.com/search?q=server+side+rendering) using the `browser` environmental variable as follows:
191 |
192 | ```svelte
193 |
197 |
198 | {#if browser}
199 |
200 |
201 |
202 | {/if}
203 | ```
204 |
205 | Alternatively, you can enable SSR by dynamically importing svelte-simple-modal in `onMount()` as follows:
206 |
207 | ```js
208 | import { onMount } from 'svelte';
209 |
210 | onMount(async () => {
211 | const svelteSimpleModal = await import('svelte-simple-modal');
212 | Modal = svelteSimpleModal.default;
213 | });
214 | ```
215 |
216 | ### Accessibility
217 |
218 | The library applies the following WAI-ARIA guidelines for modal dialogs
219 | automtically:
220 |
221 | - `aria-modal="true"` and `role="dialog"` are applied automatically
222 | - The tab focus is trapped in the modal
223 | - The modal is closed on pressing the `esc` key
224 |
225 | To further improve the accessibility you'll have to either provide a label via
226 | [`ariaLabel`](https://www.w3.org/TR/wai-aria-1.1/#aria-label) or reference a
227 | title element via [`ariaLabelledBy`](https://www.w3.org/TR/wai-aria-1.1/#aria-labelledby).
228 | The `ariaLabel` is automatically omitted when `ariaLabelledBy` is specified.
229 |
230 | ## API
231 |
232 | ### Component API
233 |
234 | The `` component accepts the following optional properties:
235 |
236 | | Property | Type | Default | Description |
237 | | ------------------------- | ---------------------------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
238 | | **show** | Component \| null | `null` | A Svelte component to show as the modal. See [Store API](#store-api) for details. |
239 | | **id** | string \| null | `null` | Element ID to be assigned to the modal's root DOM element. |
240 | | **ariaLabel** | string \| null | `null` | Accessibility label of the modal. See [W3C WAI-ARIA](https://www.w3.org/TR/wai-aria-1.1/#aria-label) for details. |
241 | | **ariaLabelledBy** | string \| null | `null` | Element ID holding the accessibility label of the modal. See [W3C WAI-ARIA](https://www.w3.org/TR/wai-aria-1.1/#aria-labelledby) for details. |
242 | | **closeButton** | Component \| boolean | `true` | If `true` a button for closing the modal is rendered. You can also pass in a [custom Svelte component](#custom-close-button) to have full control over the styling. |
243 | | **closeOnEsc** | boolean | `true` | If `true` the modal will close when pressing the escape key. |
244 | | **closeOnOuterClick** | boolean | `true` | If `true` the modal will close when clicking outside the modal window. |
245 | | **transitionBg** | function | `svelte.fade` | Transition function for the background. |
246 | | **transitionBgProps** | BlurParams \| FadeParams \| FlyParams \| SlideParams | `{}` | Properties of the transition function for the background. |
247 | | **transitionWindow** | function | `svelte.fade` | Transition function for the window. |
248 | | **transitionWindowProps** | BlurParams \| FadeParams \| FlyParams \| SlideParams | `{}` | Properties of the transition function for the window. |
249 | | **classBg** | string \| null | `null` | Class name for the background element. |
250 | | **classWindowWrap** | string \| null | `null` | Class name for the modal window wrapper element. |
251 | | **classWindow** | string \| null | `null` | Class name for the modal window element. |
252 | | **classContent** | string \| null | `null` | Class name for the modal content element. |
253 | | **classCloseButton** | string \| null | `null` | Class name for the built-in close button. |
254 | | **styleBg** | Record | `{}` | Style properties of the background. |
255 | | **styleWindowWrap** | Record | `{}` | Style properties of the modal window wrapper element. |
256 | | **styleWindow** | Record | `{}` | Style properties of the modal window. |
257 | | **styleContent** | Record | `{}` | Style properties of the modal content. |
258 | | **styleCloseButton** | Record | `{}` | Style properties of the built-in close button. |
259 | | **unstyled** | boolean | `false` | When `true`, the default styles are not applied to the modal elements. |
260 | | **disableFocusTrap** | boolean | `false` | If `true` elements outside the modal can be in focus. This can be useful in certain edge cases. |
261 | | **isTabbable** | (node: Element): boolean | internal function | A function to determine if an HTML element is tabbable. |
262 | | **key** | string | `"simple-modal"` | The context key that is used to expose `open()` and `close()`. Adjust to avoid clashes with other contexts. |
263 | | **setContext** | function | `svelte.setContent` | You can normally ingore this property when you have [configured Rollup properly](#rollup-setup). If you want to bundle simple-modal with its own version of Svelte you have to pass `setContext()` from your main app to simple-modal using this parameter. |
264 |
265 | ### Component Events
266 |
267 | The `` component dispatches the following events:
268 |
269 | - `open`: dispatched when the modal window starts to open.
270 | - `opened`: dispatched when the modal window opened.
271 | - `close`: dispatched when the modal window starts to close.
272 | - `closed`: dispatched when the modal window closed.
273 |
274 | Alternatively, you can listen to those events via callbacks passed to [`open()`](#open) and [`close()`](#close).
275 |
276 | ### Context API
277 |
278 | Svelte Simple Modal uses [Svelte's context API](https://svelte.dev/tutorial/context-api) to expose the `open()` and `close()` methods. You can get these methods as follows:
279 |
280 | ```js
281 | const { open, close } = getContext('simple-modal');
282 | ```
283 |
284 | #open(Component, props = {}, options = {}, callbacks = {})
285 |
286 | Opens the modal with `` 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](#parameters) except `key` and `setContext`:
287 |
288 | ```javascript
289 | {
290 | closeButton: false,
291 | closeOnEsc: false,
292 | closeOnOuterClick: false,
293 | transitionBg: fade,
294 | transitionBgProps: {
295 | duration: 5000
296 | },
297 | transitionWindow: fly,
298 | transitionWindowProps: {
299 | y: 100,
300 | duration: 250
301 | },
302 | styleBg: { backgroundImage: 'http://example.com/my-background.jpg' },
303 | styleWindow: { fontSize: '20em' },
304 | styleContent: { color: 'yellow' },
305 | styleCloseButton: { width: '3rem', height: '3rem' },
306 | disableFocusTrap: true
307 | }
308 | ```
309 |
310 | #close(callbacks = {})
311 |
312 | Closes the modal. Similar to `open()`, this method supports adding callbacks for the closing transition:
313 |
314 | ```javascript
315 | {
316 | onClose: () => { /* modal window starts to close */ },
317 | onClosed: () => { /* modal window closed */ },
318 | }
319 | ```
320 |
321 | Callbacks are triggered at the beginning and end of the opening and closing transition. The following callbacks are supported:
322 |
323 | ```javascript
324 | {
325 | onOpen: () => { /* modal window starts to open */ },
326 | onOpened: () => { /* modal window opened */ },
327 | onClose: () => { /* modal window starts to close */ },
328 | onClosed: () => { /* modal window closed */ },
329 | }
330 | ```
331 |
332 | ### Store API
333 |
334 | You can also use [Svelte stores](https://svelte.dev/tutorial/writable-stores) to open a modal using the ``'s [`show` property](#properties) as follows:
335 |
336 | ```svelte
337 |
338 |
345 |
346 |
347 |
348 |
349 |
350 |
351 |
🎉 Hi 🍾
352 | ```
353 |
354 | **Demo:** https://svelte.dev/repl/6f55b643195646408e780ceeb779ac2a
355 |
356 | An added benefit of using stores is that the component opening the modal does not have to be a parent of ``. For instance, in the example above, `App.svelte` is toggling `Popup.svelte` as a modal even though `App.svelte` is not a child of ``.
357 |
358 | #### Bind Props to a Component Shown as a Modal
359 |
360 | 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:
361 |
362 | ```svelte
363 |
370 | ```
371 |
372 | If you've worked with React/JSX then think of `const c = bind(Component, props)` as the equivalent of `const c = `.
373 |
374 | ## FAQ
375 |
376 | #### Custom Close Button
377 |
378 | **This feature requires Svelte >=v3.19!**
379 |
380 | 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 `` or `open()`.
381 |
382 | For example, your close button might look as follows:
383 |
384 | ```svelte
385 |
386 |
390 |
391 |
392 |
393 |
401 | ```
402 |
403 | Now you can set it as the default close button by passing it to `` as follows:
404 |
405 | ```svelte
406 |
407 |
412 |
413 |
414 |
415 |
416 | ```
417 |
418 | Or you can pass `CloseButton` to `open()` as shown below:
419 |
420 | ```svelte
421 |
422 |
433 |
434 |
435 | ```
436 |
437 | ## License
438 |
439 | [MIT](LICENSE)
440 |
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "svelte-simple-modal",
3 | "version": "2.0.0",
4 | "description": "A small and simple modal for Svelte",
5 | "type": "module",
6 | "svelte": "src/index.js",
7 | "main": "lib/index.js",
8 | "module": "lib/index.js",
9 | "types": "types/index.d.ts",
10 | "scripts": {
11 | "test": "echo \"Error: no test specified\" && exit 0",
12 | "build": "rm -rf lib && rm -rf types && rollup -c --bundleConfigAsCjs && sed -i '/from \"\"/d' types/index.d.ts && echo 'export { Context, Open, Close } from \"./Modal.svelte\";' >> types/index.d.ts && sed -i 's/SvelteComponentTyped/SvelteComponent/g' types/Modal.svelte.d.ts",
13 | "precommit": "NODE_ENV=production lint-staged; npm run lint",
14 | "prepare": "npm run lint && npm run build",
15 | "prerelease": "npm run lint; rm -f dist.zip; npm run build; zip dist.zip lib/* src/* types/*",
16 | "lint": "eslint src/* rollup.config.js"
17 | },
18 | "files": [
19 | "lib",
20 | "src",
21 | "types"
22 | ],
23 | "exports": {
24 | ".": {
25 | "svelte": "./src/index.js",
26 | "types": "./types/index.d.ts"
27 | }
28 | },
29 | "repository": {
30 | "type": "git",
31 | "url": "git+https://github.com/flekschas/svelte-simple-modal.git"
32 | },
33 | "keywords": [
34 | "svelte",
35 | "modal",
36 | "popup",
37 | "dialog"
38 | ],
39 | "author": "Fritz Lekschas",
40 | "license": "MIT",
41 | "bugs": {
42 | "url": "https://github.com/flekschas/svelte-simple-modal/issues"
43 | },
44 | "homepage": "https://github.com/flekschas/svelte-simple-modal#readme",
45 | "peerDependencies": {
46 | "svelte": "^5.0.0"
47 | },
48 | "devDependencies": {
49 | "@rollup/plugin-node-resolve": "^15.1.0",
50 | "@tsconfig/svelte": "^4.0.1",
51 | "eslint": "^8.43.0",
52 | "eslint-plugin-import": "^2.27.5",
53 | "eslint-plugin-svelte": "^2.31.1",
54 | "husky": "^4.3.8",
55 | "lint-staged": "^10.5.4",
56 | "prettier": "^2.8.8",
57 | "prettier-plugin-svelte": "^2.10.1",
58 | "pretty-quick": "^3.1.3",
59 | "rollup": "^3.25.2",
60 | "rollup-plugin-svelte": "^7.1.5",
61 | "sveld": "^0.20.0",
62 | "svelte": "^4.0.0",
63 | "svelte-eslint-parser": "^0.31.0",
64 | "typescript": "^5.1.3"
65 | }
66 | }
67 |
--------------------------------------------------------------------------------
/rollup.config.js:
--------------------------------------------------------------------------------
1 | /* eslint-env node */
2 | import node from '@rollup/plugin-node-resolve';
3 | import svelte from 'rollup-plugin-svelte';
4 | import { sveld } from 'sveld';
5 |
6 | import { readFileSync } from 'fs';
7 | const pkg = JSON.parse(readFileSync('./package.json'));
8 |
9 | const production = !process.env.ROLLUP_WATCH;
10 |
11 | export default {
12 | input: pkg.svelte,
13 | output: { format: 'es', file: pkg.module },
14 | plugins: [
15 | svelte({ emitCss: false }),
16 | node({
17 | browser: true,
18 | exportConditions: ['svelte'],
19 | extensions: ['.svelte'],
20 | }),
21 | production && sveld(),
22 | ],
23 | external: ['svelte', 'svelte/internal', 'svelte/transition'],
24 | };
25 |
--------------------------------------------------------------------------------
/src/Modal.svelte:
--------------------------------------------------------------------------------
1 |
38 |
39 |
469 |
470 |
471 |
472 | {#if Component}
473 |