vue-js-modal/README.md at e59a5a3ce8af17ef2f570dcb36eda8f5bb0470e6

KevinMidboe/vue-js-modal

Fork 0

mirror of https://github.com/KevinMidboe/vue-js-modal.git synced 2025-10-29 18:00:20 +00:00

Files

Luca Degasperi fc3d6a3dbe Update README.md

2018-03-29 15:25:48 +02:00

12 KiB

Raw Blame History

Changelog on Medium

Demo: http://vue-js-modal.yev.io/

Install

npm install vue-js-modal --save

How to use

Include plugin in your main.js file.

import VModal from 'vue-js-modal'

Vue.use(VModal)

/*
By default plugin will use "modal" name for the component.
If you need to change it, you can do so by providing "componentName" param.

Example:

Vue.use(VModal, { componentName: "foo-modal" })
...
<foo-modal name="bar"></foo-modal>
*/

Create modal:

<modal name="hello-world">
  hello, world!
</modal>

Call it from anywhere in the app:

methods: {
  show () {
    this.$modal.show('hello-world');
  },
  hide () {
    this.$modal.hide('hello-world');
  }
}

You can easily send data into the modal:

this.$modal.show('hello-world', { foo: 'bar' })

And receive it in beforeOpen event handler:

<modal name="hello-world" @before-open="beforeOpen"/>

methods: {
  beforeOpen (event) {
    console.log(event.params.foo);
  }
}

If you use Bower package manager - you will have to initialize library differently:

Vue.use(window["vue-js-modal"].default);

Dialog

It is a simplified version of the modal, which has most parameters set by default and is pretty useful for quick prototyping, showing alerts or creating mobile-like modals.

To start using <v-dialog/> you must set dialog: true in plugin configuration:

Vue.use(VModal, { dialog: true })

And include it in your project:

<v-dialog/>

Call it (all params except of “text” are optional):

this.$modal.show('dialog', {
  title: 'Alert!',
  text: 'You are too awesome',
  buttons: [
    {
      title: 'Deal with it',
      handler: () => { alert('Woot!') }
    },
    {
      title: '',       // Button title
      default: true,    // Will be triggered by default if 'Enter' pressed.
      handler: () => {} // Button click handler
    },
    {
      title: 'Close'
    }
 ]
})

Dynamic Modals

In order to instantiate modals at runtime (for lazy-loading or decluttering templates), it is possible to create modals dynamically.

To start using this feature you must set dynamic: true in plugin configuration:

Vue.use(VModal, { dynamic: true })

And include the <modals-container/> component it in your project:

<modals-container/>

Call it (the first argument is the component definition, the second are component properties, the third modal parameters, and the fourth the modal event listeners):

this.$modal.show({
  template: `
    <div>
      <h1>This is created inline</h1>
      <p>{{ text }}</p>
    </div>
  `,
  props: ['text']
}, {
  text: 'This text is passed as a property'
}, {
  height: 'auto'
}, {
  'before-close': (event) => { console.log('this will be called before the modal closes'); }
})

It can also be used with .vue files:

import MyComponent from './MyComponent.vue'

this.$modal.show(MyComponent, {
  text: 'This text is passed as a property'
}, {
  draggable: true
})

Other than defining the name modal parameter, it's also possible to close dynamic modals emitting a 'close' event:

this.$modal.show({
  template: `
    <div>
      <p>Close using this button:</p>
      <button @click="$emit('close')">Close</button>
    </div>
  `
})

For more examples please take a look at vue-js-modal.yev.io.

Note: keep in mind that there are some limitations for using dynamic modals. If you need full functionality then use ordinary modal instead.

SSR

Include plugin in your nuxt.config.js file:

module.exports = {
  plugins: ['~plugins/vue-js-modal']
}

And your plugins/vue-js-modal.js will look like:

import Vue from 'vue'
import VModal from 'vue-js-modal/dist/ssr.index'

Vue.use(VModal)

For full demo please look at demo/server_side_rendering

Extracted CSS

There is also a ssr build with css file extracted. Take a look in /dist folder.

Properties

Name	Required	Type	Default	Description
name	true	[String, Number]		Name of the modal
delay	false	Number	0	Delay between showing overlay and actual modal box
resizable	false	Boolean	false	If true, allows to resize modal window, keeping it in the center of the screen.
adaptive	false	Boolean	false	If true, modal box will try to adapt to the window size
draggable	false	[Boolean, String]	false	If true, modal box will be draggable.
scrollable	false	Boolean	false	If `height` property is `auto` and the modal height exceeds window height - you will be able to scroll modal
reset	false	Boolean	false	Resets position and size before showing modal
clickToClose	false	Boolean	true	If set to `false`, it will not be possible to close modal by clicking on the background
transition	false	String		Transition name
classes	false	[String, Array]	'v--modal'	Classes that will be applied to the actual modal box, if not specified, the default 'vue--modal' class will be applied
width	false	[String, Number]	600	Width in pixels or percents (e.g. 50 or "50px", "50%")
height	false	[String, Number]	300	Height in pixels or percents (e.g. 50 or "50px", "50%") or `"auto"`
minWidth	false	Number (px)	0	The minimum width to which modal can be resized
minHeight	false	Number (px)	0	The minimum height to which modal can be resized
maxWidth	false	Number (px)	Infinity	The maximum width of the modal (if the value is greater than window width, window width will be used instead
maxHeight	false	Number (px)	Infinity	The maximum height of the modal (if the value is greater than window height, window height will be used instead
pivotX	false	Number (0 - 1.0)	0.5	Horizontal position in %, default is 0.5 (meaning that modal box will be in the middle (50% from left) of the window
pivotY	false	Number (0 - 1.0)	0.5	Vertical position in %, default is 0.5 (meaning that modal box will be in the middle (50% from top) of the window

Events

Name	Description
before-open	Emits while modal is still invisible, but was added to the DOM
opened	Emits after modal became visible or started transition
before-close	Emits before modal is going to be closed. Can be stopped from the event listener calling `event.stop()` (example: you are creating a text editor, and want to stop closisng and ask user to correct mistakes if text is not valid)
closed	Emits right before modal is destoyed

Example:

<template>
  <modal name="example"
         :width="300"
         :height="300"
         @before-open="beforeOpen"
         @before-close="beforeClose">
    <b>{{time}}</b>
  </modal>
</template>
<script>
export default {
  name: 'ExampleModal',
  data () {
    return {
      time: 0,
      duration: 5000
    }
  },
  methods: {
    beforeOpen (event) {
      console.log(event)
      // Set the opening time of the modal
      this.time = Date.now()
    },
    beforeClose (event) {
      console.log(event)
      // If modal was open less then 5000 ms - prevent closing it
      if (this.time + this.duration < Date.now()) {
        event.stop()
      }
    }
  }
}
</script>

Example with a dynamic modal:

export default {
  name: 'ExampleModal',
  data () {
    return {
      time: 0,
      duration: 5000
    }
  },
  methods: {
    openModal () {
      this.$modal.show({
        template: `<b>{{time}}</b>`,
        props: ['time']
      }, {
        time: this.time
      }, {
        width: 300,
        height: 300
      }, {
        'before-open': this.beforeOpen,
        'before-close': this.beforeClose
      })
    },
    beforeOpen (event) {
      console.log(event)
      // Set the opening time of the modal
      this.time = Date.now()
    },
    beforeClose (event) {
      console.log(event)
      // If modal was open less then 5000 ms - prevent closing it
      if (this.time + this.duration < Date.now()) {
        event.stop()
      }
    }
  }
}
</script>

This example, initializes time variable every time the modal is being opened. And then forbits closing it for the next 5000 ms

Other

Height: "auto"

From v1.2.6 height can be set to "auto". If you want to be able to scroll modal in case it's height exceeds window height - you can set flag scrollable="true".

p.s. scrollable will only work with height="auto".

Example:

<modal name="foo" height="auto" :scrollable="true">...</modal>

Auto height:

Scrollable content & auto height:

Close button

If you want to have a Close (x) button in the top-right corner, you can use "top-right" slot for it. There is deliberately no predefined Close button style - you will have to implement/use your own button.

Example:

<template>
  <modal name="foo">

    <div slot="top-right">
      <button @click="$modal.hide('foo')">
        ❌
      </button>
    </div>

    Hello, ☀️!

  </modal>
</template>

Draggable handler

Draggable property can accept not only Boolean but also String paramenters. With String value, you can specify a CSS selector to the element which will be a "handler" for dragging.

Example:

<modal name="bar" draggable=".window-header">
  <div class="window-header">DRAG ME HERE</div>
  <div>
     Hello, 🌎!
  </div>
</modal>

Overlay background color

If you want to change overlay background color, you can easily do it using css.

For all modals:

.v--modal-overlay {
  background: red;
}

For specific modal:

.v--modal-overlay[data-modal="my_modal_name"] {
  background: transparent;
}

Fullscreen

<modal name="fs" :adaptive="true" width="100%" height="100%">
Dont forget about close button :)
</modal>

Check out

Check out my other projects:

Developers

To run an example:

# Clone repo
git clone https://github.com/euvl/vue-js-modal.git

# Run unit tests
npm run unit

# Run linter
npm run lint

# Build main library for client & ssr
cd vue-js-modal
npm install
npm run build

# Build and run demo
cd demo/client_side_rendering
npm install
npm run dev

12 KiB Raw Blame History Unescape Escape

Vue.js modal

Simple to use, highly customizable, mobile friendly Vue.js 2.0+ modal with SSR support. http://vue-js-modal.yev.io/

Install

How to use

Dialog

Dynamic Modals

SSR

Extracted CSS

Properties

Events

Other

Height: "auto"

Close button

Draggable handler

Overlay background color

Fullscreen

Check out

Developers

12 KiB

Raw Blame History