# vue-pro-modal

> Vue plugin for creating modal windows. It can be used both in traditional style and programmatically.

Latest version **1.0.18** (published 2022-11-08) · MIT license · 0 weekly downloads

## Install

```sh
npm install vue-pro-modal
pnpm add vue-pro-modal
yarn add vue-pro-modal
bun add vue-pro-modal
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.18 |
| Published | 2022-11-08 |
| First published | 2020-12-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 2.1 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Rustam |
| Maintainers | 17axah |
| Keywords | vue-modal, modal, vue-pro-modal, vue dialog, programmatic modal |

## Links

- npm: https://www.npmjs.com/package/vue-pro-modal
- Repository: https://github.com/17axah/vue-pro-modal
- Homepage: https://github.com/17axah/vue-pro-modal#readme
- Issues: https://github.com/17axah/vue-pro-modal/issues
- npm.io page: https://npm.io/package/vue-pro-modal

## Dependencies (3)

- [portal-vue](https://npm.io/package/portal-vue.md) ^2.1.7
- [vue-body-scroll-lock](https://npm.io/package/vue-body-scroll-lock.md) ^2.0.2
- [@juggle/resize-observer](https://npm.io/package/@juggle/resize-observer.md) ^3.2.0

## Alternatives

- [react-native-root-siblings](https://npm.io/package/react-native-root-siblings.md) — 102.9K weekly downloads
- [@praxisui/dialog](https://npm.io/package/@praxisui/dialog.md) — 2.0K weekly downloads
- [easy-toggle-state](https://npm.io/package/easy-toggle-state.md) — 350 weekly downloads
- [ngx-lightbox-evp](https://npm.io/package/ngx-lightbox-evp.md) — 19 weekly downloads
- [react-native-modal-translucent-axton](https://npm.io/package/react-native-modal-translucent-axton.md) — 4 weekly downloads

## Recent versions

- 1.0.18 (latest) — 2022-11-08
- 1.0.17 — 2022-11-08
- 1.0.16 — 2022-03-16
- 1.0.15 — 2022-03-07
- 1.0.14 — 2022-03-07
- 1.0.13 — 2022-03-07
- 1.0.12 — 2022-03-07
- 1.0.11 — 2022-03-04
- 1.0.10 — 2022-03-04
- 1.0.9 — 2022-03-03
- 1.0.8 — 2021-05-12
- 1.0.7 — 2021-05-07
- 1.0.6 — 2021-04-27
- 1.0.5 — 2021-04-27
- 1.0.4 — 2021-04-27
- … 3 more at https://npm.io/package/vue-pro-modal/versions

## README

# Vue pro modal

Vue plugin for creating modal windows. It can be used both in traditional style and programmatically.

## Installation

```bash
$ npm i vue-pro-modal
```

<br>
<br>

## Nuxt
```js
// nuxt.config.js
export default {
    ...
    modules: [
        'vue-pro-modal/nuxt',
    ],
};
```

Create modal component in the «components» directory and add VModalTarget component to main component.

<br>
<br>

## Usage (programmatically)

```js
import Vue from 'vue';
import VueModal from 'vue-pro-modal';
import 'vue-pro-modal/dist/vue-pro-modal.css';

const options = {
  import: (name) => import(`@/components/${name}.vue`),
};

Vue.use(VueModal, options);
```

Create modal component in the «components» directory:

```js
// components/Modal.vue
<template>
    <v-modal>
        content
    </v-modal>
</template>
```

Add target component in root app:

```js
// App.vue
<template>
    <div>
        <div>
            <router-view />
        </div>

        <v-modal-target />
    </div>
</template>
```

Calling modal:

```js
export default {
    methods: {
        open() {
            this.$modal.open('Modal');
        },
    },
};
```

### More about calling modals programmatically:
The programmatic call of modals dynamically load components from the directory specified in the import option.
The import option is required.
Installing the plugin connects the components globally, and also adds the *$modal* property, which has the following properties and methods:

**$modal.$store** - state of modals:
```js
[
    {
        id: string,
        name: string,
        props: object,
        listeners: object,
        eventBus: object
    }
]
```

**$modal.open** - Method for calling modals. Returns a promise that is resolved when the opening animation ends.
```js
/**
 * @param {String} name - name or namespace of component.
 * @param {Object} props - props of component.
 * @param {Object} listeners - event listeners of component.
 *
 * @returns {Promise}
 */
this.$modal.open(name, props, listeners).then(() => {
    console.log('opened');
});
```

**$modal.close** - Method for closing modals. Returns a promise that is resolved when the closing animation ends.
```js
/**
 * An modal can be found by name, id, or index.
 * If no argument is passed function will close the last modal.
 *
 * @param {String|Number} name
 *
 * @returns {Promise}
 */
this.$modal.open(name, props, listeners).then(() => {
    console.log('opened');
});
```

**$modal.closeAll** - Method for closing all modals.

<br>
<br>

## Usage (v-model)

```js
import 'vue-pro-modal/dist/vue-pro-modal.css';
```

```js
<template>
    <div>
        <button v-on:click="modal = true">
            show modal
        </button>

        <v-modal v-model="modal">
            content
        </v-modal>
    </div>
</template>

<script>
import { VModal } from 'vue-pro-modal';

export default {
    components: {
        VModal,
    },
    data() {
        return {
            modal: false
        };
    },
};
</script>
```

<br>
<br>

## Options
Name                | Type               | Default   | Description
--------------------|--------------------|-----------|--------------
transition          | string             | 'scale'   | Transition name to display modal.
loadingTransition   | string             | 'fade'    | Transition name to display modal after loading.
appear              | boolean            | false     | To apply a transition on the initial render.
overlay             | boolean            | true      | Display overlay modal.
layout              | boolean            | true      | Display background modal.
fullscreen          | boolean            | false     | Fullscreen modal.
persistent          | boolean            | false     | Persistent modal. When you click on the overlay, the modal will twitch.
scrollLock          | boolean            | true      | Body scroll lock.
scrollLockGapMethod | string             | 'none'    | Gap method  while blocking scrolling
closeOnOverlay      | boolean            | true      | Close modal on click overlay.
closeOnEscape       | boolean            | true      | Close modal on press ESC key.
noPadding           | boolean            | false     | Without paddings (.modal__container).
noRadius            | boolean            | false     | Without border-radius (.modal__container).
focusableElement    | string,null        | null      | Focus element after opening modal.
zIndex              | number,string      | 1000      | z-index modal.
import              | function           | —         | Function for importing components

<br>
<br>

## Components
The module exports components: VModal, VModalTarget, VModalContent, VModalClose

### VModal
The main component for creating a modal window

<br>

#### Props
Name                | Type                | Default   | Description
--------------------|---------------------|-----------|--------------
value               | boolean             | false     | Value for v-model.
portal              | boolean             | true      | Using portal.
mountTo             | string              | 'body'    | A querySelector String defining the DOM element to mount the modal to.
modalClass          | string,array,object | —         | CSS class for .modal
containerClass      | string,array,object | —         | CSS class for .modal__container
width               | string              | —         | Modal width
maxWidth            | string              | —         | Modal max-width
height              | string              | —         | Modal height
maxHeight           | string              | —         | Modal max-height

***You can also specify props from options***

<br>

#### slots
Name                | props
--------------------|------------------------------------------
loading             | —
default             | { close } - Function to close modal

<br>

#### events
* before-open
* open
* after-open
* before-close
* close
* after-close

#### example
```js
<template>
    <v-modal v-model="modal" persistent v-slot="{ close }" v-on:after-open="afterOpen">
        <template v-slot:loading>
            <i class="icon-loading" />
        </template>
        <h2>
            title
        </h2>
        <button v-on:click="close">
            close modal
        </button>
    </v-modal>
</template>

<script>
export default {
    data() {
        return {
            modal: false,
        };
    },
    methods: {
        afterOpen() {
            console.log('modal opened');
        },
    },
};
</script>
```

<br>
<br>

### VModalTarget
Component target. Required to programmatically use modals.

#### Props
Name                | Type                | Default   | Description
--------------------|---------------------|-----------|--------------
transition          | string              | 'scale'   | Transition name

***When using programmatically, the transition must be reassigned here and not the Modal props***

Or you can pass the transition through the props:
```js
this.$modal.open('modals/Test', { transition: 'my-transition-name' })
```

<br>
<br>

### VModalContent
Component for creating modals that have a header footer and a body. In this case, the maximum body height will be calculated using the following formula: (100vh - (header height) - (footer height) - (modal paddings)).
In this case, the height of the header and footer is tracked and can change at any time.

#### slots
Name                | props
--------------------|------------------------------------------
header              | —
body                | —
footer              | —

<br>

#### example
```js
<tempate>
<v-modal>
    <v-modal-content>
        <template v-slot:header>
            modal header
        </template>
        <template v-slot:body>
            modal body
        </template>
        <template v-slot:footer>
            modal footer
        </template>
    </v-modal-content>
</v-modal>
</template>
```

<br>
<br>

### VModalClose
Close button component.

#### Props
Name                | Type                | Default   | Description
--------------------|---------------------|-----------|--------------
tag                 | string              | 'button'  | tag name

<br>

#### slots
Name                | props
--------------------|--------------------------
default             | —

slot for changing default icon (x)

<br>

#### example
```js
<tempate>
<v-modal>
    <v-modal-content>
        <template v-slot:header>
            <div style="display: flex; justify-content: space-between; align-items: center;">
                <div>
                    modal header
                </div>
                <div>
                    <v-modal-close />
                </div>
            </div>
        </template>
        <template v-slot:body>
            modal body
        </template>
        <template v-slot:footer>
            modal footer
        </template>
    </v-modal-content>
</v-modal>
</template>
```

---
_Source: https://npm.io/package/vue-pro-modal · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._